Authentication and API Keys

Most Chab /v1 requests authenticate with team API keys. A key belongs to a team, not a person. Browser sessions and personal user tokens cannot call /v1 directly. Active browser-trial visitors can also issue short-lived guest trial API credentials for a small, guest-scoped /v1 surface; see Guest Trial API Credentials.

Send the key as a bearer token:

Authorization: Bearer CHAB_API_KEY

Foundation endpoint guides include runnable curl examples.

Revoked, disabled, or expired team keys are rejected anywhere Chab accepts them as bearer credentials, including older API routes.

Creating a Key

Create team API keys in the dashboard under Team -> API Tokens. Choose a token name, optional expiration, foundation scopes, product-feature mode, spending policy, project access, and optional IP allow/deny rules.

Chab shows the secret once when the key is created. Store it securely before leaving the page.

Creating a key does not by itself unlock every billable operation endpoint. Paid operation calls require an eligible paid plan, a healthy subscription, the operation family included in the plan, and enough credits. Foundation endpoints remain available to scoped keys regardless of plan.

Verified free accounts can create bounded API keys for the 21 provider operations listed in All tools, when the particular operation is available and free credits can be used. Free API keys may include api:credits:read, the scopes required by those operations, and file read/write for conversion; they do not gain project management, paid-credit budgets, persistent webhooks, callbacks, or connected-account Mail and Drive scopes. Accepted free starts spend the account's one-off signup-bonus free-credit lot and do not fall back to paid credits. These promotional credits do not refresh monthly. The homepage has two example forms; guests can use all tools through API/CLI, local MCP, or hosted MCP without signing up.

Paid and legacy-eligible keys default to these scopes:

• api:examples:write
• api:projects:read
• api:credits:read

api:examples:write, api:search:read, api:seo:read, api:business:read, api:contact:write, api:scrape:read, api:screenshot:write, api:convert:write, api:translate:write, api:llm:read, api:llm:write, api:research:write, api:mail:read, api:mail:write, api:mail:send, api:drive:read, and api:drive:write map to documented /v1 routes. A scope does not itself make an operation start available. Each of the tools still needs a ready provider, available credits and passing risk checks before the specific request can start. Connected-account Mail and Drive operations are not part of guest access. api:seo:read gates the keyword endpoints and the domain overview/backlink endpoints. Project, credit, usage, billing, token, file, and webhook routes are also available; see Automation and Management, Files, and Webhooks.

Scopes

Scopes use this format:

api:<family>:<action>

Use :read for operations that retrieve or return existing data. Use :write for operations that generate, render, transform, create, update, delete, or otherwise mutate data. Some project-management scopes use the more specific actions :create, :update, and :delete.

"All product features" snapshots every live assignable product feature at the time the policy is saved. It is not a wildcard and does not automatically grant future features. Foundation, account, and project-management scopes remain independent selections.

Each scope below can be assigned and gates a published /v1 endpoint. Permission alone does not bypass project, spending, connection, plan, or management-approval requirements. “When available” means the operation starts only while the tool is switched on, a provider is ready, and your access, credits and risk checks allow the request. “Not open yet” means the routes exist but are not available to customers yet.

Permissions remain independent. New scopes are never added to existing keys automatically.

Legacy wildcard keys are normalized to the live assignable scopes that existed at migration time; the wildcard is removed so later scopes are not granted automatically. The compatibility team:view-members ability is preserved. Any other unknown legacy ability stops migration for explicit operator review instead of being silently added or discarded.

The three mail scopes are independent. Read does not imply write, write does not imply read or send, and send does not imply either. A reply draft needs the write scope plus current read capability; sending it later still needs the send scope. See Mail Endpoints.

The drive read and write scopes are independent. Neither implies the other. Writes also require manager-approved connection consent and the exact current capability. See Drive Endpoints.

Token controls

New keys start with product features, credit spending, and project access set to none. Spending may be changed to all or to a non-renewing capped allowance. A capped allowance reports its limit, settled, held, and remaining credits. Reducing it below already held and settled exposure is rejected. Free API keys must keep spending and project access set to none; free-funded operation reservation uses the account's promotional free-credit lots instead of a token paid-credit allowance.

Guest Trial API Credentials

An active browser-trial visitor can create a temporary bearer credential from the trial page that holds the guest trial cookie. The page displays the secret once and keeps a revocation list for active credentials.

For a developer console check from the same browser tab, use the session-backed web endpoint with the current XSRF token:

const xsrf = decodeURIComponent(
  document.cookie
    .split("; ")
    .find((cookie) => cookie.startsWith("XSRF-TOKEN="))
    ?.slice("XSRF-TOKEN=".length) ?? "",
);

const response = await fetch("/guest-trial/api-credentials", {
  method: "POST",
  credentials: "same-origin",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-Requested-With": "XMLHttpRequest",
    "X-XSRF-TOKEN": xsrf,
  },
  body: JSON.stringify({ name: "Laptop CLI" }),
});

console.log(await response.json());

Credential creation is browser mediated: it requires the guest trial cookie, same-origin request headers, the session CSRF token, and any verification challenge Chab asks for. Clients should read the challenge details from challenge_required, complete the browser challenge, and retry creation with the named challenge response field.

The response returns access_token once. Chab stores only a hash. Guest trial credentials:

• expire after 24 hours
• are limited to 3 active credentials per guest trial
• can be revoked from the same browser trial page

Use the returned secret as a /v1 bearer token:

curl https://www.chab.ai/v1/credits \
  -H "Authorization: Bearer chab_guest_..."

Guest credentials are scoped to the same guest beneficiary and the same guest promotional grant pool as the browser trial. Creating or rotating credentials does not create more free value; concurrent guest credentials share the same balance, caps, risk counters, and active-operation limit. Guest trial credits are one-off promotional value and do not refresh monthly.

Supported /v1 guest credential routes include:

• GET /v1/me
• GET /v1/credits
• the provider start routes listed in All tools
• guest-owned /v1/files upload, read, and download routes for conversion inputs
• GET /v1/llm/models for model discovery
• GET /v1/operations/{id}
• GET /v1/operations/{id}/result
• POST /v1/operations/{id}/cancel
• GET /v1/operations/{id}/artifacts/{artifact_id}
• GET /v1/operations/{id}/artifacts/{artifact_id}/download

Operation starts still require Idempotency-Key. Accepted guest credential starts return /v1/operations/... status, result, cancel, and artifact URLs. An active guest credential can read or cancel operations created under that same credential. Other credentials issued to the same guest share the free balance and limits, but cannot read or cancel those operations.

Creating guest credentials has separate rolling limits for the browser trial, its source network, and the service. If issuance returns 429, follow Retry-After; revoking an existing key does not reset a rolling limit.

Guest credentials cannot access team resources, management APIs, operation history listing, connected accounts, hosted MCP operation transport, paid-only routes, projects, tokens, billing settings, webhooks, mail, or drive. Unsupported guest credential /v1 routes return operation_not_available_on_free before route controllers or team-resource scope checks run. Expired or claimed browser trials can return signup_required. Trial credits are one-off, and a new guest credential does not renew an expired balance. Create a free account to keep going, or sign in if you already have one.

Project access is none, selected, or all. Selected grants include only current projects in the token's team; all also includes projects created later. Operations without a project are unaffected. Project-not-found, cross-team, deleted, and ungranted resources share the not_found response. Project grants and selected_project_ids currently use team-scoped numeric project IDs. Connected-data requests add an exact numeric Chab connection ID and capability decision after project authorization. The connection ID is globally allocated, but it never bypasses team/project ownership. A family scope such as api:mail:read or api:drive:read, a project grant, an active usable connection, and the exact observed capability are all required; none implies another. Connection collections are constrained without inventing a broad "list connections" capability. Cancelling an operation created by the same token remains possible after its project grant is removed, while reads and artifact delivery use current grants. Scopes and project grants are both required: a grant never supplies a missing operation or project-management scope. Queued project-bound or connected-data work, and callbacks, recheck token lifecycle, operation scope, and project access before the next delivery. Ordinary queued work that has no project or connection keeps its accepted authorization when a key is rotated. Continuation checks do not apply the inbound IP rules. A removed grant blocks callback delivery without a network retry, while already accepted billing still settles against its retained snapshots. New credit reservations and downloads recheck the key's current lifecycle and spending allowance when reserving credits. A revocation or spending restriction that commits first also applies to a request already waiting to reserve credits. Previously accepted work still settles incurred costs against its current hold, including when that hold grew while settlement was waiting. Removing a credential does not erase its billing history. Cancellation by the API key that created an operation still works after a project grant or connection capability is removed, but the cancellation response omits protected result data.

IP rules accept exact IPv4/IPv6 addresses and CIDR ranges, with at most 64 rules. Deny rules take precedence. When allow rules exist, the source must match one; restricted keys fail closed if Chab cannot determine the client address. Only deployment-configured trusted proxies may supply forwarded client IPs. The API uses the same trusted-proxy boundary as the web app unless its ingress has an explicitly configured narrower boundary. If the client address cannot be established, restricted requests fail closed rather than trusting a caller- supplied forwarded header. Every successful feature, IP, spending, project, expiration, administrative hold, or revoke change advances the key's shared policy revision. Administrative holds can only be placed or cleared by an operator. Stale dashboard edits are rejected without merging and must be reviewed against the latest safe policy summary.

Authentication and Scope Errors

Authentication and scope errors are not retryable without changing the request or key.

The response body uses the standard error envelope:

{
  "error": {
    "code": "api_scope_missing",
    "message": "The API token is missing the scope required for this operation.",
    "retryable": false
  },
  "request_id": "req_123"
}

Inspecting the Current Key

Use GET /v1/me to confirm the authenticated principal. Team keys return the stable public token id, granted scopes, current policy revision, feature snapshot, redacted IP-rule counts, spending state, and project grants. Guest trial credentials return the guest id, credential id, granted guest scopes, transport, expiry, and current guest grant summary. This endpoint requires a valid team API key or guest trial credential but no operation scope. It never returns IP addresses, CIDR ranges, raw principal ids, or bearer secrets.

curl https://www.chab.ai/v1/me \
  -H "Authorization: Bearer CHAB_API_KEY"

Example response:

{
  "data": {
    "principal_type": "team_api_token",
    "team_id": 123,
    "token_id": "456",
    "token_public_id": "870b679b-210c-4d33-9d2c-a5b091693f42",
    "scopes": [
      "api:examples:write"
    ],
    "token_controls": {
      "policy_revision": 3,
      "feature_access": {"mode": "selected", "snapshot_stale": false},
      "ip_restrictions": {"restricted": true, "allow_rule_count": 1, "deny_rule_count": 0},
      "spending": {"mode": "capped", "active_reserved_credits": 5, "allowance": {"version": 1, "limit_credits": 100, "settled_credits": 20, "held_credits": 5, "remaining_credits": 75}},
      "project_access": {"mode": "selected", "selected_project_ids": [42], "selected_count": 1}
    },
    "request_id": "req_123"
  },
  "meta": {
    "request_id": "req_123"
  }
}

Revoking a Key

Revoke a team API key from Team -> API Tokens. Revoked keys are rejected by /v1 team-key authentication, cannot be restored, and appear in the revoked-key history. A revoked key's name can be reused for a new key. This history shows only lifecycle metadata such as the key name, revocation time, and last-use time; it does not expose the key's former scopes or policy details. The retained API aliases also enforce Chab key revocation.

Retained API aliases

The older /api/projects and /api/credits/balance and /api/credits/transactions routes accept Chab keys with the same lifecycle, IP, scope, and project restrictions. Their historical response shapes remain: project lists are bare arrays, and project errors use reason_code. Project access none returns an empty project list; unselected or foreign projects return 404. Creating a project requires project access all. Revoked or expired keys receive 401, and disabled or IP-denied keys receive 403. Using these aliases does not widen a Chab key's permissions. If a key retains older permission settings after an upgrade, those restrictions also apply to the retained routes.

Use /v1/me to check a Chab key's identity. Chab keys receive 403 from the legacy /api/user endpoint; it does not expose a team record to API keys. Existing signed-in browser sessions continue to use that endpoint.

For browser-based CLI sign-in, see CLI Device Authentication.