OAuth2 Clients

Register and manage OAuth2 clients for machine-to-machine authentication using the client_credentials grant.

OAuth2 clients are the registered identities behind the machine-to-machine client_credentials flow. Each client is identified by a client_id and authenticates with a client_secret that is returned once at creation time and cannot be retrieved afterward - only rotated.

One feature, two pages. This page covers client registration, scopes, setup allow-lists, and secret management. OAuth2 (Machine-to-Machine) covers the token endpoint, scope resolution, and token claims.

Concepts

Scopes (Action Dimension)

Each client is granted a set of scopes that define what actions it can perform. Scopes follow a resource:action pattern and can include wildcard patterns (e.g., sms:* or *). Wildcards are expanded at token issuance time.

Available scope categories include:

Category	Example Scopes
SMS	sms:send, sms:read, sms:consent:write
Email	email:send, email:read, email:template:read, email:template:write
iMessage	imessage:send, imessage:read
Outbound Voice	outbound-voice:send
Ringless Voicemail	ringless-voicemail:send, ringless-voicemail:read
Twilio Setup	twilio-setup:read, twilio-setup:write, twilio-setup:create, twilio-setup:credentials, twilio-setup:access-token, twilio-setup:verify-webhook
Twilio Phone Number	twilio-phone-number:read, twilio-phone-number:write
SendBlue Setup	sendblue-setup:read, sendblue-setup:create
SendBlue Phone Number	sendblue-phone-number:read, sendblue-phone-number:write
Voice Compliance	compliance:voice:read, compliance:voice:write
SMS Compliance	compliance:sms:read, compliance:sms:write
Regulatory Compliance	compliance:regulatory:read, compliance:regulatory:write
Use Case	use-case:read, use-case:write
Client Management	clients:admin

Setup Allow-List (Resource Dimension)

A setup is a provisioned channel configuration - a telephony, email, or messaging configuration - that channel operations act on. Each client specifies which setups it can access through allowed_setup_ids. This is either:

• An explicit list of setup IDs - the client can only operate on these specific setups. Setup IDs are validated against existing setups at creation and update time.
• The wildcard ["*"] - the client can access all setups (intended for first-party services). The wildcard and explicit IDs are mutually exclusive.

Secret Management

Client secrets are high-entropy tokens generated by the platform. Only the hash of the secret is stored - the raw secret is returned once at creation time and once when rotated. It cannot be retrieved afterward.

Secret rotation is a hard swap with no grace period. The previous secret is invalidated immediately when a new one is issued.

Endpoints

All client management endpoints require an access token carrying the clients:admin scope; requests without it receive 403 Forbidden. The clients:admin scope is granted only by exact name - it is never matched by a wildcard grant.

Create an OAuth2 Client

POST /v1/oauth/client

Registers a new OAuth2 client. Returns the client credentials, including the secret (shown only once).

Request Body:

Field	Type	Required	Description
name	string	Yes	Display name (1-64 characters, alphanumeric with spaces, hyphens, and underscores)
description	string	Yes	Description (1-256 characters)
granted_scopes	array of strings	Yes	Scopes or wildcard patterns to grant (at least one required)
allowed_setup_ids	array of UUIDs or ["*"]	Yes	Setup IDs the client can access, or ["*"] for all setups

Response (201):

Field	Type	Description
client_id	UUID	The public client identifier
client_secret	string	The raw secret - returned once and never again
name	string	Display name
description	string	Description
granted_scopes	array of strings	Granted scopes
allowed_setup_ids	array of strings	Allowed setup IDs

Error Responses:

Status	Description
404	One or more allowed_setup_ids do not exist
422	Request body failed validation

Update an OAuth2 Client

PUT /v1/oauth/client/{client_id}

Updates an existing OAuth2 client. All fields are optional, but at least one must be provided. The secret cannot be changed through this endpoint - use the rotate-secret endpoint instead.

Path Parameters:

Parameter	Type	Description
client_id	UUID	The client to update

Request Body:

Field	Type	Required	Description
name	string	No	Updated display name
description	string	No	Updated description
granted_scopes	array of strings	No	Updated scopes
allowed_setup_ids	array of UUIDs or ["*"]	No	Updated setup allow-list

Response (200):

Field	Type	Description
client_id	UUID	The client identifier
name	string	Display name
description	string	Description
granted_scopes	array of strings	Granted scopes
allowed_setup_ids	array of strings	Allowed setup IDs

Error Responses:

Status	Description
404	Client not found, or an allowed_setup_id does not exist
422	No fields supplied, or a field failed validation

Delete an OAuth2 Client

DELETE /v1/oauth/client/{client_id}

Revokes an OAuth2 client. The client can no longer authenticate after deletion. This is a soft delete for audit retention - the client record is preserved but marked as revoked. Re-deleting a revoked client returns 404.

Path Parameters:

Parameter	Type	Description
client_id	UUID	The client to revoke

Response: 204 No Content

Error Responses:

Status	Description
404	Client not found (already revoked, or never existed)

Rotate Client Secret

POST /v1/oauth/client/{client_id}/rotate-secret

Issues a new client secret, immediately invalidating the previous one. The new secret is returned once and cannot be retrieved afterward.

Path Parameters:

Parameter	Type	Description
client_id	UUID	The client whose secret to rotate

Response (200):

Field	Type	Description
client_secret	string	The new raw secret - returned once and never again

Error Responses:

Status	Description
404	Client not found