API authentication

Every path below is relative to your deployment — https://api.usesink.co on the hosted service.

The hosted deployment answers on two names: api.usesink.co for the API, and the apex usesink.co for the dashboard, the installer and anything a person opens in a browser — share links, invites and the legal pages. Both serve the same routes, so a call to either works; api.usesink.co is the deliberate name for programmatic use.One consequence worth knowing: install.sh bakes the apex into the CLI as its stored api_url, so a freshly installed client talks to usesink.co until you point it elsewhere with sink login --api-url or SINK_API_URL.

Authenticating a request

Two credentials work, and the sk- prefix is what tells them apart.

curl https://api.usesink.co/workspaces/ \
  -H 'X-API-Key: sk-a1b2c3d4e5f60718'

curl https://api.usesink.co/workspaces/ \
  -H 'Authorization: Bearer sk-a1b2c3d4e5f60718'

curl https://api.usesink.co/workspaces/ \
  -H 'Authorization: Bearer eyJhbGciOi…'

An API key is minted in the dashboard or by POST /keys/, belongs to a user, and is what the CLI and any automation should use. A session token comes from a browser login and is short-lived.

Workspace scope

On a path that contains {workspace_id}, that value decides the scope. On a path without one, Sink reads the X-Workspace-Id header, and failing that the credential’s own scope — the workspace claim on a session token, or the holder’s current workspace for an API key. A caller who is not a member of the resolved workspace gets 403.

Interactive docs (/docs, /redoc, /openapi.json) are served only when a deployment runs with DEBUG enabled, so they are not available on the hosted instance.

Accounts

Method	Path	Body	Notes
`POST`	`/auth/get-started`	`email`, `first_name`, `last_name`, `password`, `created_at`; `middle_name` optional	Creates a password account and its first workspace. `409` if the address is taken.
`POST`	`/auth/login`	Form: `username`, `password`	Returns an access token and sets an HttpOnly refresh cookie.
`POST`	`/auth/refresh`	Refresh cookie, or `{ "refresh_token": "…" }`	Cookie first, body as fallback. Rotates the refresh token.
`POST`	`/auth/logout`	—	Revokes the current session and clears the cookie. Reports how many sessions were revoked.
`GET`	`/auth/me`	—	The authenticated user’s profile.
`PATCH`	`/auth/me`	`name`, or `first_name` / `middle_name` / `last_name`	`name` wins when both are sent. Email cannot be changed here.
`DELETE`	`/auth/me`	`{ "password": "…" }`	Irreversible. Deletes owned workspaces and leaves the rest; reports the counts.

Verifying an email

Method	Path	Purpose
`POST`	`/auth/request-otp`	Mail the signed-in account a six-digit code.
`POST`	`/auth/verify-email`	Same thing, under the name the dashboard’s banner uses.
`POST`	`/auth/verify`	Submit it: `{ "otp": 123456 }`.

Codes expire on their own timer, and a fresh one is refused while a live one is outstanding.

SSO

Method	Path	Purpose
`GET`	`/auth/google-login`	Redirect into Google’s consent screen.
`GET`	`/auth/google-callback`	Complete the Google round trip.
`GET`	`/auth/github-login`	Redirect into GitHub.
`GET`	`/auth/github-callback`	Complete the GitHub round trip.

These are browser flows. A first sign-in through either creates the account and its first workspace.

API keys

curl -X POST https://api.usesink.co/keys/ \
  -H 'X-API-Key: sk-…' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "ci", "description": "Deploy bot", "expires_at": 43200 }'

string

required

How the key shows up in the dashboard.

string

Free text — what this key is for.

integer

Lifetime in minutes from now, not a timestamp. 43200 is thirty days. Omit for a key that does not expire.

The response carries token — the actual credential. Only its SHA-256 digest is stored, so this is the one and only time it is shown.

Method	Path	Purpose
`POST`	`/keys/`	Mint a key.
`GET`	`/keys/`	List the account’s active keys. Never returns tokens.
`PATCH`	`/keys/{key_id}`	Update `name`, `expires_at` or `is_revoked`.
`POST`	`/keys/{key_id}`	Revoke this key.

A revoked or expired key answers 401 on its next use, with a message distinguishing the two.

Sessions

Method	Path	Purpose
`GET`	`/sessions/`	List the account’s live sessions — address, user agent, created and expiry.
`POST`	`/sessions/{session_id}/`	Revoke one session.
`POST`	`/sessions/`	Revoke every session on the account.

Sessions are one per device: signing in again from the same user agent revokes that device’s previous session rather than sitting alongside it.

Errors

Status	Meaning
`401`	No credential, or one that is invalid, revoked or expired.
`402`	The workspace’s plan does not allow this. See Plans and limits.
`403`	Authenticated, but not a member of the workspace or team — or not its owner.
`404`	Not found, or not visible from this scope.
`409`	Conflicts with something that already exists.
`422`	The body failed validation.
`429`	Rate limited. Honour `Retry-After`.

Errors and limits has the full picture, including rate-limit headers and the 207 case on secret reads.

Getting Started

Guides

Security & Access

CLI Reference

API Reference

API authentication

Authenticating a request

Workspace scope

Accounts

Verifying an email

SSO

API keys

Sessions

Errors

​Authenticating a request

​Workspace scope

​Accounts

​Verifying an email

​SSO

​API keys

​Sessions

​Errors

Authenticating a request

Workspace scope

Accounts

Verifying an email

SSO

API keys

Sessions

Errors