Authentication#

API version: v1

Every v1 endpoint requires authentication. The only credential type is a Hosted API token, sent in the Authorization header as a bearer token.

Creating a token#

Create a token from the Tokens section of your account settings at hosted.doltdb.com/settings/tokens. Give it a name that says where it will be used — deploy pipeline, staging bootstrap — since that name is how you will identify it later.

Copy the token immediately. Only a hash of it is stored, so the secret is shown once and cannot be recovered afterwards. If you lose it, delete the token and create another.

Tokens are prefixed hsat.v1..

Using a token#

Send it as a bearer token on every request:

curl 'https://hosted.doltdb.com/api/v1/user' \
  -H 'Authorization: Bearer hsat.v1.YOUR_TOKEN_HERE'

GET /api/v1/user is the cheapest way to check a credential: a 200 confirms the token is valid and shows whose access it carries.

In a script, keep the token in an environment variable rather than in the source:

export HOSTED_API_TOKEN='hsat.v1.YOUR_TOKEN_HERE'

curl 'https://hosted.doltdb.com/api/v1/deployments/acme' \
  -H "Authorization: Bearer $HOSTED_API_TOKEN"

Permissions#

A token carries the full permissions of the user who created it. There are no per-token scopes in v1 — anything you can do in the web UI, a token of yours can do through the API, including creating deployments, which incurs cost.

Access to a particular deployment still follows that deployment’s own roles. A deployment you cannot see returns 404 rather than 403, so the API never reveals that a deployment exists to someone without access to it.

Expiry and revocation#

Every token has an expiry date, chosen when you create it — 30, 60, or 90 days, or one year. There is deliberately no non-expiring option; rotate long-lived automation on a schedule that matches the expiry you pick.

Delete a token from the same settings page to revoke it immediately. The tokens table also shows when each token was last used, and from where, which is the fastest way to find out whether a token is still in service before you delete it.

Failure responses#

Both are returned as Problem documents. See the v1 overview for the error model.