REST API: OAuth App resource

An OAuth App resource represents an account-level OAuth app. Use the OAuth App resource to create and manage OAuth apps and rotate their client secrets.

(information)

Note

The OAuth App resource only supports account OAuth apps that use the Client Credentials grant type. To generate an access token with an OAuth app's credentials, use the OAuth Token API.

All requests use the base URL https://iam.twilio.com/v1/Account/OAuthApps.

You can authenticate requests using either HTTP Basic authentication or OAuth.

For HTTP Basic authentication, use your Account SID and Auth Token or an API key SID and secret.

For OAuth, send an access token from the OAuth Token API as a Bearer token in the Authorization header.

If your request includes a body, it must be formatted as JSON.

OAuth App properties

Property	Type	Description
`sid`	string	The unique identifier of the OAuth app, which is also its client ID. Starts with `OQ`.
`type`	string	The OAuth grant type of the OAuth app, which is always `Client Credential`.
`friendly_name`	string	The name of the OAuth app.
`description`	string	A description of the OAuth app.
`status`	string	The status of the OAuth app, for example `ACTIVE`.
`policy`	object	The permissions granted to the OAuth app. See Policy object.
`access_token_ttl`	integer	The length of time in minutes that access tokens issued for the OAuth app remain valid.
`date_created`	string	The date and time the OAuth app was created, in ISO 8601 format.
`created_by`	string	The email address of the user who created the OAuth app.
`creator_sid`	string	The SID of the user who created the OAuth app. Starts with `US`.
`secret`	string	The client secret of the OAuth app. Returned when you create, update, or rotate the secret of an OAuth app. Not returned when you fetch or list OAuth apps.

Policy object

Property	Type	Description
`allow`	array of strings	The permissions the OAuth app can use, for example `/twilio/messaging/messages/read`.

(warning)

Warning

An account OAuth app can have up to 100 permissions in policy.allow. Wildcards, such as /twilio/messaging/*, aren't allowed, so each entry must be an explicit permission. See Scopes/Permissions available for OAuth apps.

Create an OAuth App resource

POST https://iam.twilio.com/v1/Account/OAuthApps

Create an OAuth app.

Encoding type: application/json

Request body parameters

Parameter	Type	Required	Description
`type`	string	yes	The OAuth grant type of the OAuth app. Must be `Client Credential`.
`owner_sid`	string	yes	The SID of the account that owns the OAuth app. Must match the account you authenticate with.
`friendly_name`	string	yes	The name of the OAuth app. Maximum 64 characters.
`description`	string	no	A description of the OAuth app. Maximum 140 characters.
`policy`	object	yes	The permissions to grant the OAuth app. `policy.allow` must contain at least one permission. See Policy object.
`access_token_ttl`	integer	no	The length of time in minutes that access tokens remain valid. Maximum 43200 (30 days). Defaults to 60 (1 hour).
`token_endpoint_auth_method`	string	no	How the OAuth app authenticates when it requests an access token. The only supported value is `client_secret_basic`.

1curl -X POST "https://iam.twilio.com/v1/Account/OAuthApps" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
3-H "Content-Type: application/json" \
4-d '{
5    "type": "Client Credential",
6    "owner_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7    "friendly_name": "My OAuth App",
8    "description": "Sends messages from my backend service",
9    "policy": {
10        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
11    },
12    "access_token_ttl": 60
13}'

If the request succeeds, Twilio returns 201 Created with the new OAuth App resource.

1{
2    "type": "Client Credential",
3    "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4    "friendly_name": "My OAuth App",
5    "description": "Sends messages from my backend service",
6    "date_created": "2026-06-15T12:00:00Z",
7    "created_by": "user@example.com",
8    "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
9    "secret": "{CLIENT_SECRET}",
10    "status": "ACTIVE",
11    "policy": {
12        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
13    },
14    "access_token_ttl": 60
15}

(warning)

Warning

Keep your OAuth app secure by storing the secret in a secrets manager, such as AWS Secrets Manager or HashiCorp Vault, as soon as you receive it. Never hard-code it or commit it to version control. Fetch and list responses don't include the secret. If you lose it or it's exposed, rotate the secret.

Fetch an OAuth App resource

GET https://iam.twilio.com/v1/Account/OAuthApps/{sid}

Retrieve an OAuth app. For security reasons, the response doesn't include the secret.

Path parameters

Parameter	Type	Required	Description
`sid`	string	yes	The SID of the OAuth app to fetch. Starts with `OQ`.

1curl -X GET "https://iam.twilio.com/v1/Account/OAuthApps/OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

If the request succeeds, Twilio returns 200 OK with the OAuth App resource.

1{
2    "type": "Client Credential",
3    "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4    "friendly_name": "My OAuth App",
5    "description": "Sends messages from my backend service",
6    "date_created": "2026-06-15T12:00:00Z",
7    "created_by": "user@example.com",
8    "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
9    "status": "ACTIVE",
10    "policy": {
11        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
12    },
13    "access_token_ttl": 60
14}

List OAuth App resources

GET https://iam.twilio.com/v1/Account/OAuthApps

Retrieve a list of OAuth apps that belong to the account you authenticate with.

1curl -X GET "https://iam.twilio.com/v1/Account/OAuthApps" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

If the request succeeds, Twilio returns 200 OK with the OAuth App resources in the content array.

1{
2    "content": [
3        {
4            "type": "Client Credential",
5            "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6            "friendly_name": "My OAuth App",
7            "description": "Sends messages from my backend service",
8            "date_created": "2026-06-15T12:00:00Z",
9            "created_by": "user@example.com",
10            "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
11            "status": "ACTIVE",
12            "policy": {
13                "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
14            },
15            "access_token_ttl": 60
16        }
17    ]
18}

Update an OAuth App resource

PUT https://iam.twilio.com/v1/Account/OAuthApps/{sid}

Update an OAuth app. Only the fields you include in the request change.

Encoding type: application/json

Path parameters

Parameter	Type	Required	Description
`sid`	string	yes	The SID of the OAuth app to update. Starts with `OQ`.

Request body parameters

Parameter	Type	Required	Description
`friendly_name`	string	no	The name of the OAuth app. Maximum 64 characters.
`description`	string	no	A description of the OAuth app. Maximum 140 characters.
`policy`	object	no	The permissions to grant the OAuth app. See Policy object.
`access_token_ttl`	integer	no	The length of time in minutes that access tokens remain valid. Maximum 43200 (30 days).

(warning)

Update the policy

The update request completely overwrites the existing policy of the OAuth app. Include all the permissions the OAuth app needs in the policy object. To remove a permission while keeping others, include only the permissions to keep.

1curl -X PUT "https://iam.twilio.com/v1/Account/OAuthApps/OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
3-H "Content-Type: application/json" \
4-d '{
5    "friendly_name": "My Updated OAuth App",
6    "description": "Updated description",
7    "access_token_ttl": 120
8}'

If the request succeeds, Twilio returns 200 OK with the updated OAuth App resource, including its current secret.

1{
2    "type": "Client Credential",
3    "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4    "friendly_name": "My Updated OAuth App",
5    "description": "Updated description",
6    "date_created": "2026-06-15T12:00:00Z",
7    "created_by": "user@example.com",
8    "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
9    "secret": "{CLIENT_SECRET}",
10    "status": "ACTIVE",
11    "policy": {
12        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
13    },
14    "access_token_ttl": 120
15}

Delete an OAuth App resource

DELETE https://iam.twilio.com/v1/Account/OAuthApps/{sid}

Delete an OAuth app. After deletion, you can't generate access tokens with the OAuth app's credentials.

(warning)

OAuth app deletion is permanent and can't be undone

Deleting an OAuth app also invalidates all access tokens issued for it. If you only need to address compromised credentials, rotate the client secret instead of deleting the OAuth app.

Path parameters

Parameter	Type	Required	Description
`sid`	string	yes	The SID of the OAuth app to delete. Starts with `OQ`.

1curl -X DELETE "https://iam.twilio.com/v1/Account/OAuthApps/OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

If the request succeeds, Twilio returns 204 No Content with no body.

Rotate the secret of an OAuth App resource

POST https://iam.twilio.com/v1/Account/OAuthApps/{sid}/secret

Generate a new client secret for an OAuth app. You can set gracePeriodInSeconds to keep the old secret valid while you roll out the new one.

Path parameters

Parameter	Type	Required	Description
`sid`	string	yes	The SID of the OAuth app whose secret to rotate. Starts with `OQ`.

Query parameters

Parameter	Type	Required	Description
`gracePeriodInSeconds`	integer	no	The length of time in seconds that the old secret remains valid. Must be between 0 and 2678400. If set to 0, the old secret becomes invalid immediately.

1curl -X POST "https://iam.twilio.com/v1/Account/OAuthApps/OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/secret?gracePeriodInSeconds=86400" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

If the request succeeds, Twilio returns 200 OK with the OAuth App resource, including the new secret.

1{
2    "type": "Client Credential",
3    "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4    "friendly_name": "My OAuth App",
5    "description": "Sends messages from my backend service",
6    "date_created": "2026-06-15T12:00:00Z",
7    "created_by": "user@example.com",
8    "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
9    "secret": "{NEW_CLIENT_SECRET}",
10    "status": "ACTIVE",
11    "policy": {
12        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
13    },
14    "access_token_ttl": 60
15}

Errors

If a request fails, Twilio returns a JSON error body with code, message, more_info, and status fields.

Status	Description
`400`	The request is invalid. For example, a field exceeds its maximum length, the policy is empty or contains a wildcard, or `gracePeriodInSeconds` is out of range.
`401`	The request isn't authenticated.
`403`	The credentials don't have permission to perform this action.
`404`	The OAuth app doesn't exist or has been deleted.