Authentication

Authentication Guide

The Smoo AI API uses OAuth 2.0 client credentials flow for machine-to-machine authentication. This guide walks you through creating credentials and authenticating your API requests.

Overview

All API requests (except the token endpoint) require a valid Bearer token. You obtain tokens by exchanging your client credentials at the token endpoint.

OAuth 2.0

Client credentials grant type for server-to-server communication.

Bearer Tokens

JWT tokens included in the Authorization header of every request.

Token Expiry

Tokens expire after 1 hour. Refresh by requesting a new token.

1. Create API Credentials

Navigate to Settings > API Keys in the Smoo AI dashboard. Click Create Client to generate a new client ID and secret pair.

Prefer the terminal? The th CLI mints the same clients: th api keys create --type m2m for a machine-to-machine secret, or th api keys create --type b2m --allowed-origin https://app.example.com for a browser-to-machine publishable key. Manage them with th api keys list, th api keys rotate, and th api keys revoke.

Store your secret securely

The client secret is shown only once. Store it in a secure location like a secrets manager or environment variable. Never commit secrets to source control.

2. Request an Access Token

Exchange your client credentials for an access token by making a POST request to the token endpoint.

Skip the boilerplate: run th api login and the th CLI performs this exchange for you, caching the token (th api whoami shows the active identity and TTL). Reads SMOOAI_CLIENT_ID / SMOOAI_CLIENT_SECRET from the environment, or pass --client-id / --client-secret.

curl -X POST https://auth.smoo.ai/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

3. Use the Token

Include the access token in the Authorization header of all API requests.

curl https://api.smoo.ai/organizations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rate Limiting

The API enforces rate limits to ensure fair usage. The default limit is 100 requests per 60 seconds per authenticated token.

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Wait until the reset time before retrying.