API Authentication & Tokens

Generating a Token#

API tokens are created from the client portal. You must be logged in as the client whose data you want to access.

1. Log in to the client portal.
2. Click your name or avatar in the top-right corner and select Profile.
3. Scroll to the API Tokens section.
4. Enter a descriptive name for the token (e.g., My Integration, Billing Dashboard).
5. Click Create Token.
6. Copy the token immediately — it is displayed only once.

[!WARNING] The token is shown in full only at creation time. Once you dismiss or navigate away from the page, you cannot retrieve it again. Store it in a secrets manager or environment variable immediately.

Using a Token in Requests#

Include the token in the Authorization header of every request:

Authorization: Bearer {your-token}

Example: curl#

curl https://billing.example.com/api/v1/me \
  -H "Authorization: Bearer ot_live_abc123xyz..."

Example: JavaScript (fetch)#

const response = await fetch('https://billing.example.com/api/v1/me', {
  headers: {
    'Authorization': 'Bearer ' + token,
    'Accept': 'application/json'
  }
});
const data = await response.json();

Example: PHP#

$ch = curl_init('https://billing.example.com/api/v1/me');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

Invalid or Expired Tokens#

If a token is missing, malformed, or has been revoked, the API returns:

HTTP/1.1 401 Unauthorized

{
  "message": "Unauthenticated."
}

Check that:

• The Authorization header is present and spelled correctly.
• The token value is complete (no truncation).
• The token has not been revoked (see below).

Revoking a Token#

To revoke a token:

1. Log in to the client portal.
2. Go to Profile → API Tokens.
3. Click Revoke next to the token you want to remove.

Revoked tokens are immediately invalidated. Any requests using a revoked token will receive a 401 response.

Token Security Best Practices#

[!TIP] If you suspect a token has been compromised, revoke it immediately and generate a new one. There is no expiry — tokens remain valid until explicitly revoked.