Accounts & authentication

Use a one-time link

POST /api/v1/auth/tickets/redeem

Uses a one-time link to sign in, link an account or sign up. For the web app's own pages only. Signs in, links the account at a provider that the link carries, or creates the account it is for, under name; each signs the browser in with the session cookie.

Parameters

Originheader · required · string

This server's origin. Required for this browser sign-in step.

Idempotency-Keyheader · optional · string

Makes a retry safe: a request with the same key and the same method, path, and body as an earlier one gets the earlier response instead of doing the work again. 1 to 255 visible ASCII characters; use a new key for each new request, such as a UUID. Keys are kept per caller for a day, and ignored for requests without credentials.

Minimum length: 1 · Maximum length: 255

Example request

curl --request POST 'https://commitscale.com/api/v1/auth/tickets/redeem' \
  --header 'Origin: https://commitscale.com' \
  --header 'Content-Type: application/json' \
  --data '{
  "token": "email-fragment-token"
}'

Example values illustrate the format. Use your own credentials and identifiers.

Request body

application/json

A one-time link's token, from /login/continue#token=…. A signup also names the account to create.

data_sharingoptional · object

Only for account creation, from the person's confirmation form.

Fields of data_sharing

opted_inrequired · boolean: Whether the person explicitly chose to share scrubbed Free-plan check data.
wording_versionoptional · string: Required and current when opting in. Withdrawal needs no version.

nameoptional · string

Public username to create when accepting a sign-up ticket.

tokenrequired · string

One-time secret from the sign-in or invitation link's fragment.

Responses

200 Signed in; the session cookie is set.

application/json

{
  "handle": "user:alex",
  "is_admin": false,
  "kind": "user",
  "name": "alex"
}

Who is making a request.

handlerequired · string: The caller's handle, such as user:alex.
is_adminrequired · boolean: Whether this person has server management rights. Delegated credentials do not inherit them.
kindrequired · user / agent / runner: Whether the caller is a person, an agent or a runner.
namerequired · string: The caller's user, agent or runner name.
owneroptional · string: The owning person, for an agent.
signed_in_withoptional · cscale_web / email_link / passkey / oidc: For a browser session: how it began.
token_expires_atoptional · string (date-time): When the credential expires, in UTC. Omitted for a credential without an expiry.

RateLimit and RateLimit-Policy describe the request rate. Follow Retry-After when a response asks you to wait.

Problem responses

Errors use application/problem+json. Act on the stable code, and follow next when present. See the problem format.

check_key_scope403

A check-only key may call the test check, read its own usage and acceptance rule, contact support, and withdraw data sharing.

Use a person's sign-in for account management. More agent power needs the owner's passkey; this key cannot widen itself.

signup_closed403

Open sign-up is turned off on this server.

Ask for an invite, or sign in to an existing account.

feature_off403

The namespace plan does not include this feature.

Retrying on the same plan will not help. GET /api/v1/namespaces/{namespace}/plan, and the namespace's Plan page in Settings, show what its plan includes.

invalid_token401

The token is unknown, expired, or revoked, its agent was revoked, or an OAuth token was used outside its MCP resource.

Stop using it. Sign in again, or ask the owner to create a replacement agent key.

forbidden403

The caller may not do this: only people may, only owners may, or the agent was not given this repository or write access.

Stop. Retrying will not help. Ask the owner for the access, or leave the step to a person.

already_exists409

Something with that name exists, or its current state does not allow this request.

Use the one that exists, or choose another name.

invalid_request400 / 413 / 415 / 422

The request is malformed or breaks a rule, such as a title that is too long, or a body that is not the expected JSON.

Fix the request as detail says. The same request fails the same way.

quota_exceeded422 / 429

With 429, the caller used its requests for the minute. With 422, a count limit was reached.

With 429, wait Retry-After seconds and retry. With 422, remove one first.

idempotency_key_reused409 / 422

The idempotency key was already used for a different request.

Use a new key for each new request, and the same key only for a retry of the same request.

idempotency_key_in_use409

The first request with this key is still running, including a queued model question, or it succeeded with a secret, such as a new token, which is never replayed.

When Retry-After is set, retry then with the same key. Otherwise the first request succeeded: do not repeat it.

expired_token400

A device login code, sign-up, sign-in link, or passkey prompt expired or was already used.

Start a new flow. If a sign-up already created the account but its key was lost, the person signs in to revoke and replace that key.

access_denied400

A device login was denied or refused after five wrong codes, or the passkey does not sign in here.

Stop. After five wrong codes, start a new login; otherwise, sign in another way.

internal500

The server failed, and logged why.

Retry after Retry-After seconds. A write is safe to retry with the same idempotency key.

unavailable503

With 502, a service the server needs did not answer, such as a sign-in provider. With 503, the server is busy, such as when a workspace is locked or host lookups are full, or a write with an idempotency key runs long: that write goes on, and its answer is kept for the key.

With 502, retry later, or sign in another way. With 503, retry after Retry-After seconds, using the same idempotency key for a write; a long-running write can then replay its answer.