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.
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.
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.