API reference

Authentication

Every endpoint except the public catalog uses Bearer auth. Two kinds of key work:

• Project-scoped key (prefix tsk_): issued per project in the console's Token Center; it can only reach credentials and scopes explicitly granted to that project.
• Connect Tesska access_token: a per-user key obtained by third-party apps through the OAuth authorization-code flow; use it directly as a Bearer token against /v1/*.
• GET /v1/platforms is a public catalog and needs no auth.

POST /v1/login

The core broker endpoint: exchange one granted platform account for one access. The response shape depends on how the credential is held — Mode A returns a short-lived token (or raw, if explicitly enabled); Mode B returns pending_approval and pushes the owner's phone. Body fields:

• platform (required) — platform id, see GET /v1/platforms.
• account (required) — account identifier of the vaulted credential.
• scope (optional) — string or string[]; defaults to the grant's full scopes, anything beyond them returns 403.
• clientPubKey (required for Mode B) — the caller's ephemeral ECDH-P256 public key; on approval the credential is sealed to it in the owner's browser (HKDF-SHA256 + AES-256-GCM).

GET /v1/grants

Introspection: lists the grants this key can call (project × credential × scopes). The response contains no secrets or tokens.

GET /v1/platforms

Public platform catalog: metadata for supported and reserved adapters, no auth required. status is ready (available) or planned (reserved); missing platforms can be requested from the console.

GET /v1/approvals/:id

Poll a Mode B approval. status is pending / approved / denied / expired; an id that doesn't belong to this key's project returns 404.

• On approved you get resultCt + resultMeta: the credential was decrypted in the owner's browser and sealed to your clientPubKey — only your ephemeral private key can open it.
• The ciphertext is delivered exactly once: the server burns it after the first read, and later polls return only the status without resultCt.
• The server holds zero plaintext throughout — everything it stores and relays is ciphertext.

GET /oauth/authorize

The Connect Tesska authorization-code endpoint (a browser redirect, not an API call), with PKCE S256 enforced. An unregistered client_id or a redirect_uri outside the allowlist is blocked outright without redirecting; other protocol errors bounce back to redirect_uri as error=unsupported_response_type / invalid_request / invalid_scope. Query parameters:

• client_id (required) — obtained by registering in the console's Developer apps.
• redirect_uri (required) — must exactly match the registered allowlist.
• response_type (required) — always code.
• scope (required) — space-delimited, must stay within the app's allowed scopes.
• state (recommended) — echoed back verbatim, protects against CSRF.
• code_challenge (required) — BASE64URL(SHA256(code_verifier)).
• code_challenge_method (required) — only S256 is accepted.

POST /oauth/token

Exchange the authorization code for an access_token. application/x-www-form-urlencoded (JSON also accepted); client credentials go in the body or via HTTP Basic. The access_token is a per-user scoped key: use it directly as a Bearer token against /v1/*; it is long-lived but the user can revoke it anytime under Connected apps. Parameters:

• grant_type (required) — authorization_code.
• code (required) — the authorization code from the redirect.
• code_verifier (required) — the PKCE plaintext verifier.
• redirect_uri (required) — same as in the authorization request.
• client_id / client_secret — body or HTTP Basic; the client_secret is shown only once at registration.

Error codes

Errors from /v1/* are uniformly { "error": "..." } with the matching HTTP status; the OAuth endpoints follow OAuth 2.0 error conventions (error=invalid_request and friends).

• 400 — body is not valid JSON, platform/account missing, unsupported platform, or Mode B call without clientPubKey.
• 401 — Bearer key missing, invalid, or revoked.
• 403 — no such grant, scope exceeded, platform not on the project allowlist, credential frozen, or raw delivery not enabled.
• 404 — approval request not found, or not owned by this key's project.
• 429 — per-minute rate limit of the grant exceeded.
• 501 — capability not live yet (e.g. proxy-login session delivery, coming soon).
• 502 — upstream platform failed to mint the token.

Audit

Every call — success or failure — writes an audit event: caller project and key, target platform and account, scopes, outcome, and other metadata, traceable in the console. Anomalous patterns (bursts of failures, unusual calls) trigger anomaly detection and push alerts.

Webhooks & SDKsPlanned

Outbound webhooks and official SDKs are not released yet — this documentation only describes what's live. In the meantime:

• Approval results: poll GET /v1/approvals/:id (see above).
• SDKs: every endpoint is plain HTTPS + JSON, so any HTTP client works with the examples on this page.