Copy page

Get started

Authentication

Every request to the Tomba API carries an API key and your account secret as headers. Apps that act on behalf of other Tomba users use OAuth 2.0 access tokens instead.

Request headers

Your account has one secret, shared by all of its keys. Keys are what you create, name, expire, and revoke for each integration.

Keep both values on a server (Security). Anyone who obtains them can spend your credits, and every key of an account shares the account's rate limits.

Get your key and secret

Create keys and copy your secret on the API keys page of the dashboard. GET /v1/me also returns the secret, as secret_token.

Key expiry

• Every key expires. The default and maximum lifetime is 365 days. When you create a key through the API, set expires_in_days to any value from 1 to 365.
• Tomba emails the account owner 30 days, 7 days, and 1 day before a key expires.
• GET /v1/keys returns each key's expires_at and expired fields.

A request with an expired key fails with status 400 and error type api_key_expired. The response includes an X-Tomba-Key-Expired header with the expiry time in RFC 3339 format:

Code
{
    "errors": {
        "type": "api_key_expired",
        "message": "This API key expired on March 1, 2025. Create a new key at https://app.tomba.io/api",
        "code": 400
    }
}

Rotate keys

To replace a key without downtime:

1. Create a new key in the dashboard or with POST /v1/keys.
2. Deploy the new key to your integration.
3. Delete the old key in the dashboard or with DELETE /v1/keys/{id}.

Code
curl -X POST "https://api.tomba.io/v1/keys" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "billing-service", "expires_in_days": 90}'

The response returns the new key in data.message:

Code
{ "data": { "id": 1234, "message": "ta_xxxx" } }

PUT /v1/keys/{id} rotates a key in place instead: it issues a new value with a new 365-day term, and the old value stops working immediately. The response doesn't include the new value; read it with GET /v1/keys/{id}.

To rotate the secret, use Settings in the dashboard. Every key then works only with the new secret, so update all integrations at once.

The number of active keys an account can hold depends on its plan; expired keys don't count toward it. In a workspace, GET /v1/keys returns the keys of every member, including their values.

OAuth 2.0

Apps that act on behalf of other Tomba users, such as MCP clients and workflow tools, use OAuth 2.0 and send the access token as Authorization: Bearer <access_token>.

Request only the scopes your app needs:

GET /v1/logs and GET /v1/usage don't accept OAuth tokens; call them with a key and secret. Users review and revoke app access under Connected apps.

The remote MCP server accepts additional credential formats; its page lists them.

Endpoints without authentication

The Logo API and GET /v1/domain-status need no credentials.

Errors

Errors lists every error type.