Authentication

The TAO Public API uses API-key based authentication. Call https://api.tao.com/auth with an API key to get an access token and refresh token, then include the access token in the Authorization header on protected API requests.

Authorization: Bearer <access_token>

Tokens are opaque to clients. Do not parse them or depend on token contents; use the fields returned by the auth response.

Base URL

Use the public API host for all requests:

https://api.tao.com

Get an access token

POST https://api.tao.com/auth supports two modes through the type field.

Mode	Use for	Result
API_KEY	Server-side clients that hold an API key.	Returns an access token, token type, refresh token, and expiry.
REFRESH_TOKEN	Exchanging an existing refresh token.	Returns a new access token. It may not issue a new refresh token.

API key

POST https://api.tao.com/auth
Content-Type: application/json

{
  "type": "API_KEY",
  "username": "<api_key_id>",
  "password": "<api_key_secret>"
}

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "<expires_in_seconds>",
  "refresh_token": "<refresh_token>"
}

Refresh token

POST https://api.tao.com/auth
Content-Type: application/json

{
  "type": "REFRESH_TOKEN",
  "username": "<api_key_id>",
  "refresh_token": "<refresh_token>"
}

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "<expires_in_seconds>"
}

Protected endpoint responses

Protected endpoints may return:

Status	Meaning
401 Unauthorized	Missing, invalid, expired, or otherwise unaccepted token.
403 Forbidden	The authenticated client is not allowed to access the requested resource.
429 Too Many Requests	Rate limit exceeded. Retry behavior depends on the response headers.

Auth service errors

The /auth service documents these errors:

Status	Meaning
400 Bad Request	Missing or invalid request input.
401 Unauthorized	Credentials or refresh token was not accepted.
404 Not Found	Unknown auth endpoint path.

Protected routes may document 403 and 429. Treat those as protected-route responses, not /auth behavior.