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: smoo api keys create --type m2m for a machine-to-machine secret, or smoo api keys create --type b2m --allowed-origin https://app.example.com for a browser-to-machine publishable key. Manage them with smoo api keys list, smoo api keys rotate, and smoo 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 smoo auth login --m2m and the th CLI performs this exchange for you, caching the token (smoo auth whoami shows the active identity and TTL). Pass --client-id / --client-secret, or omit them to be prompted interactively.

curl -X POST https://auth.smoo.ai/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "provider=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 300 requests per 60 seconds per authenticated token.

Header	Description
RateLimit-Limit	Maximum requests per window
RateLimit-Remaining	Remaining requests in current window
RateLimit-Reset	Seconds until the current window resets

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