OAuth2 (Machine-to-Machine)

Machine-to-machine OAuth2 client credentials flow for programmatic access to the Platform API.

The platform supports an OAuth2 client credentials flow for machine-to-machine (M2M) integrations. Registered OAuth2 clients authenticate with their credentials and receive short-lived access tokens scoped to authorized actions and resources.

One feature, two pages. This page covers the token endpoint, scope resolution, and token claims. OAuth2 Clients covers the client side: registration, granted scopes, setup allow-lists, secret rotation, and revocation.

Token Endpoint

The token endpoint issues access tokens for registered OAuth2 clients.

Method	Path	Description
POST	/v1/oauth/token	Issue an access token

Request

The token endpoint accepts application/x-www-form-urlencoded requests with the following fields:

Field	Type	Required	Description
grant_type	string	Yes	Must be client_credentials
scope	string	Yes	Space-delimited list of requested scopes
client_id	string	Conditional	Required if not using HTTP Basic authentication
client_secret	string	Conditional	Required if not using HTTP Basic authentication

Client credentials can be provided in two ways (per RFC 6749 section 2.3.1):

1. HTTP Basic authentication (preferred) - Pass client_id as the username and client_secret as the password in the Authorization: Basic header.
2. Form body - Include client_id and client_secret as form fields in the request body.

If both are provided, HTTP Basic authentication takes precedence.

Response

Field	Type	Description
access_token	string	The issued access token (JWT)
token_type	string	Always bearer
expires_in	integer	Token lifetime in seconds (3600)
scope	string	Space-delimited list of granted scopes (may be a subset of requested scopes)

Scope Resolution

The issued token's scope is the intersection of the requested scopes and the client's granted scopes:

• Requested scopes that match the client's granted scope patterns are included.
• Granted patterns support wildcard matching - for example, a grant of sms:* covers sms:send.
• Certain high-privilege scopes (such as those governing client administration and credential access) are never matched by wildcard patterns. These scopes are included only when the client was explicitly granted that exact scope by name.
• Unknown or unrecognized requested scopes are silently dropped. The endpoint does not return an error for unrecognized scopes.

Token Claims

The issued access token is a JWT (RFC 9068) containing:

Claim	Description
iss / aud	Token issuer and audience
sub	The client's unique identifier
client_id	The client's unique identifier
scope	Space-delimited granted scopes
setups	The resource boundary - the list of setup IDs the client is authorized to access, or ["*"] for unrestricted access. A setup is a provisioned channel configuration (telephony, email, or messaging) that channel operations act on; see OAuth2 Clients
iat	Issued-at timestamp
exp	Expiration timestamp
jti	Unique token identifier

Error Responses

Status	Description
401	Missing client credentials (no Basic auth header and no client_id/client_secret in form body)
403	Invalid client credentials (unknown client or incorrect secret)
422	Malformed request (for example, unsupported grant_type)

No refresh token is issued. Clients using the client_credentials grant simply request a new token when the current one expires.

Example

curl -X POST https://api.platform.amigo.ai/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=sms:send sms:read"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "sms:read sms:send"
}

Client Management

OAuth2 client registration and management (create, update, delete, rotate secrets) is available through the client management endpoints. See OAuth2 Clients for details.

Client management endpoints are restricted to platform-internal access and are not reachable from the public internet. The token endpoint is publicly accessible.