---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/iam/oauth-apps/account-oauth-apps-resource#article
headline: "REST API: OAuth App resource"
description: API reference for the OAuth App resource. Create, fetch, list, update, and delete account-level OAuth apps and rotate their client secrets.
url: https://www.twilio.com/docs/iam/oauth-apps/account-oauth-apps-resource
inLanguage: en
dateModified: 2026-11-11T06:58:44.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# REST API: OAuth App resource

An OAuth App resource represents an [account-level OAuth app](/docs/iam/oauth-apps/account-oauth-apps). Use the OAuth App resource to create and manage OAuth apps and rotate their client secrets.

> \[!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](/docs/iam/oauth-apps/oauth-access-token).

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](/docs/iam/api-keys) SID and secret.

For OAuth, send an access token from the [OAuth Token API](/docs/iam/oauth-apps/oauth-access-token) 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](#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]
>
> 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](/docs/iam/oauth-apps/account-oauth-apps#scopespermissions-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](#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`.              |

```bash
curl -X POST "https://iam.twilio.com/v1/Account/OAuthApps" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
    "type": "Client Credential",
    "owner_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "friendly_name": "My OAuth App",
    "description": "Sends messages from my backend service",
    "policy": {
        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
    },
    "access_token_ttl": 60
}'
```

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

```json
{
    "type": "Client Credential",
    "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "friendly_name": "My OAuth App",
    "description": "Sends messages from my backend service",
    "date_created": "2026-06-15T12:00:00Z",
    "created_by": "user@example.com",
    "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "secret": "{CLIENT_SECRET}",
    "status": "ACTIVE",
    "policy": {
        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
    },
    "access_token_ttl": 60
}
```

> \[!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](#rotate-the-secret-of-an-oauth-app-resource).

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

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

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

```json
{
    "type": "Client Credential",
    "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "friendly_name": "My OAuth App",
    "description": "Sends messages from my backend service",
    "date_created": "2026-06-15T12:00:00Z",
    "created_by": "user@example.com",
    "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "ACTIVE",
    "policy": {
        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
    },
    "access_token_ttl": 60
}
```

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

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

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

```json
{
    "content": [
        {
            "type": "Client Credential",
            "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "friendly_name": "My OAuth App",
            "description": "Sends messages from my backend service",
            "date_created": "2026-06-15T12:00:00Z",
            "created_by": "user@example.com",
            "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "status": "ACTIVE",
            "policy": {
                "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
            },
            "access_token_ttl": 60
        }
    ]
}
```

## 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](#policy-object).            |
| `access_token_ttl` | integer | no       | The length of time in minutes that access tokens remain valid. Maximum 43200 (30 days). |

> \[!WARNING]
>
> 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.

```bash
curl -X PUT "https://iam.twilio.com/v1/Account/OAuthApps/OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
    "friendly_name": "My Updated OAuth App",
    "description": "Updated description",
    "access_token_ttl": 120
}'
```

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

```json
{
    "type": "Client Credential",
    "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "friendly_name": "My Updated OAuth App",
    "description": "Updated description",
    "date_created": "2026-06-15T12:00:00Z",
    "created_by": "user@example.com",
    "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "secret": "{CLIENT_SECRET}",
    "status": "ACTIVE",
    "policy": {
        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
    },
    "access_token_ttl": 120
}
```

## 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]
>
> Deleting an OAuth app also invalidates all access tokens issued for it. If you only need to address compromised credentials, [rotate the client secret](#rotate-the-secret-of-an-oauth-app-resource) 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`. |

```bash
curl -X DELETE "https://iam.twilio.com/v1/Account/OAuthApps/OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-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. |

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

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

```json
{
    "type": "Client Credential",
    "sid": "OQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "friendly_name": "My OAuth App",
    "description": "Sends messages from my backend service",
    "date_created": "2026-06-15T12:00:00Z",
    "created_by": "user@example.com",
    "creator_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "secret": "{NEW_CLIENT_SECRET}",
    "status": "ACTIVE",
    "policy": {
        "allow": ["/twilio/messaging/messages/create", "/twilio/messaging/messages/read"]
    },
    "access_token_ttl": 60
}
```

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