OAuth2 Clients

Understand provisioned OAuth2 clients used for machine-to-machine authentication with the client_credentials grant.

Provider M2M Clients

Provider machine-to-machine (M2M) clients let a customer's backend application obtain provider-scoped tokens through the standard client_credentials OAuth2 grant - the programmatic counterpart of the interactive provider sign-in flow. Once provisioned, a backend service authenticates with a client_id and client_secret and receives a short-lived access token scoped to the provider's identity and allowed capabilities.

Provider M2M clients are managed through a dedicated set of admin endpoints. The one-time plaintext client_secret is returned only at creation and cannot be retrieved afterward.

Lifecycle

Operation	Method	Path
Provision a client	POST	/admin/provider-m2m-clients
List clients	GET	/admin/provider-m2m-clients
Get a client	GET	/admin/provider-m2m-clients/{credential_id}
Revoke a client	POST	/admin/provider-m2m-clients/{credential_id}/revoke
Delete a client (alias for revoke)	DELETE	/admin/provider-m2m-clients/{credential_id}

Provisioning

To create a provider M2M client, supply the target workspace, the provider's entity identifier, and optionally a label, lifetime, and scope restrictions. If allowed_scopes is omitted, the client receives a default set covering session creation, session reads, and note read/write. An explicit scope list must be a non-empty subset of the platform's provider scope set.

The response includes the client_id and a one-time client_secret. Store the secret securely - it is hashed before storage and cannot be recovered.

An optional duration_days field sets the credential's lifetime (1 to 3650 days). Omitting it creates a non-expiring client that must be revoked to disable.

Minting Tokens

Use the standard token endpoint with grant_type=client_credentials, providing the client_id and client_secret. The issued token carries the provider's identity as its subject, uses provider as the principal type, and includes only the scopes allowed for the client (or a requested subset). The token shape is identical to one obtained through the interactive provider sign-in, so downstream services accept it without changes.

The scope parameter in the token request is optional. When provided, the requested scopes must be a subset of the client's allowed scopes. When omitted, all allowed scopes are issued.

The resource parameter (RFC 8707 audience indicator) is not supported for provider M2M clients.

Provider M2M tokens are short-lived and do not include a refresh token. Already-issued tokens are not revoked - they expire naturally within their short lifetime.

Revocation

Revoking a provider M2M client is a soft delete: the client is marked as revoked and the underlying credential is deactivated. New token requests with the revoked client's credentials are rejected immediately. The DELETE method on the client resource is an alias for the revoke operation and has the same effect.

Authorization

All provider M2M client management operations require workspace-admin permissions (identity:admin for the target workspace or global platform admin). The authorization gate is on the administrative act of managing machine credentials, not on the provider scopes the client is allowed to mint.

Rate Limiting

Provider M2M token minting is subject to a per-client sliding-window rate limit in addition to the existing per-IP and per-client lockout protections. Rate limit responses return HTTP 429 with a Retry-After header.

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

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.

Provisioning and Rotation

OAuth2 client creation, grant changes, revocation, and secret rotation are internal control-plane operations. The /v1/oauth/client routes are not a supported public integration surface, and no public client-management scope is available for customer credentials.

Coordinate with Concurrence to provision a client with the required action scopes and setup allow-list. Store the client secret when it is delivered because it cannot be retrieved later. A secret rotation is a hard swap: the previous secret stops working as soon as the replacement is issued.

The public machine-to-machine flow starts after provisioning. Exchange the supplied client_id and client_secret at the token endpoint as described in OAuth2 (Machine-to-Machine).