# Organization OAuth apps

Twilio's organization-level APIs only support OAuth 2.0. API keys and Auth Tokens are not supported.

Organization-level APIs can be accessed using both the [Client Credentials](/docs/iam/oauth-apps/overview#client-credentials) and [Authorization Code](/docs/iam/oauth-apps/overview#authorization-code) grant types of OAuth 2.0. The steps below explain how to manage both types of OAuth apps.

## Client Credentials

### Create an OAuth app

## Twilio Console

1. Log in to [Twilio Console](https://1console.twilio.com/) and navigate to [**Settings** > **Organization settings** > **Organization API access**](https://1console.twilio.com/organization/settings/oauth/apps).
2. Click **Create OAuth application**.
3. For **Grant type**, select **Client credentials**.
4. Enter the **Application name** and **Application description**.
5. On the **Scopes & permissions** step, select the scopes and permission you want to include in the OAuth application. Get the Permission to API mapping details [here](/docs/iam/oauth-apps/org-oauth-apps#scopespermissions-available-for-organization-oauth-apps).
6. On the **Copy secret** page, copy the credentials and store them somewhere secure.
7. Select the **Got it!** checkbox and click **Finish**.

## Legacy Console

1. In the Legacy Console, go to [**Twilio Admin**](https://admin.twilio.com/) and navigate to [**Applications** > **OAuth apps**](https://admin.twilio.com/applications/oauth).
2. On the **OAuth apps** page, click **Create OAuth application**.
3. Select grant type as **Client credentials**.
4. Enter the **Application name, Application description** and select the **Scopes & permissions** you want to include in the OAuth application. Get the Permission to API mapping details [here](/docs/iam/oauth-apps/org-oauth-apps#scopespermissions-available-for-organization-oauth-apps).
5. On the **Copy secret** page, copy the credentials and store them somewhere secure.
6. Select the **Got it!** checkbox and click **Finish**.

To generate the access token, use the [Token API](/docs/iam/oauth-apps/oauth-access-token).

### View or update an OAuth app

## Twilio Console

1. Log in to [Twilio Console](https://1console.twilio.com/) and navigate to [**Settings** > **Organization settings** > **Organization API access**](https://1console.twilio.com/organization/settings/oauth/apps).
2. On the **OAuth applications** page, click on the **App name** of the Client Credentials app you want to view or update.
3. On the **APPLICATION DETAILS** tab, view **Application name, Description of the application, Date created** and **Created by**. To update the application details, click **Edit application details** and update the details, then click **Save**.
4. On the **ACCESS SETTINGS**, view **OAuth Scopes**. You can update the **OAuth scopes**.
5. On the **Credentials** tab, view the Client ID with the ability to rotate Client Secret.

## Legacy Console

1. In the Legacy Console, go to [**Twilio Admin**](https://admin.twilio.com/) and navigate to [**Applications** > **OAuth apps**](https://admin.twilio.com/applications/oauth).
2. On the **OAuth apps** page, click on the **App name**.
3. On the OAuth apps detail page view **App name, Description of the app, Date created, Created by, OAuth Scopes** and **Client ID**. You can update the **App name, Description of the app** and **OAuth Scopes**.
4. Click **Save** to update the app or **Cancel** to go back to the OAuth apps list page.

### Delete an OAuth app

## Twilio Console

1. Log in to [Twilio Console](https://1console.twilio.com/) and navigate to [**Settings** > **Organization settings** > **Organization API access**](https://1console.twilio.com/organization/settings/oauth/apps).
2. In the **Action** column of the OAuth app you want to delete, click **Delete**.
3. In the dialog, click **Delete**.

## Legacy Console

1. In the Legacy Console, go to [**Twilio Admin**](https://admin.twilio.com/) and navigate to [**Applications** > **OAuth apps**](https://admin.twilio.com/applications/oauth).
2. On the **OAuth apps** page, click on **Delete** under Actions.
3. In the pop-up, click **Delete**.

## Authorization Code

### Create an OAuth app

## Twilio Console

1. Log in to [Twilio Console](https://1console.twilio.com/) and navigate to [**Settings** > **Organization settings** > **Organization API access**](https://1console.twilio.com/organization/settings/oauth/apps).
2. Click **Create OAuth application**.
3. Select grant type as **Authorization code**.
4. On the **Application details** page, enter the application details:
   * Application name
   * Application description
   * Company name
   * Images for the application
   * Homepage URL
   * Terms of service URL
   * Redirect URL
5. On the **Scopes & permissions** page, select the scopes and permission you want to include in the OAuth application. Get the Permission to API mapping details [here](/docs/iam/oauth-apps/org-oauth-apps#scopespermissions-available-for-organization-oauth-apps).
6. On the **Copy secret** page, copy the credentials and store them somewhere secure. For the Authorization Code grant type, Twilio generates a **Client ID**, **Client Secret**, and **Authorization URL**.
7. Select the **Got it!** checkbox and click **Finish**.

## Legacy Console

1. In the Legacy Console, go to [**Twilio Admin**](https://admin.twilio.com/) and navigate to [**Applications** > **OAuth apps**](https://admin.twilio.com/applications/oauth).
2. On the **OAuth apps** page, click **Create an OAuth app**.
3. Select grant type as **Authorization code**.
4. Enter the following details:
   * Application name
   * Application description
   * Company name
   * Images for the application
   * Homepage URL
   * Terms of service URL
   * Redirect URL
5. Select the **Scopes & permission** you want to include in the OAuth application. Get the Permission to API mapping details [here](/docs/iam/oauth-apps/org-oauth-apps#scopespermissions-available-for-organization-oauth-apps).
6. On the **Copy secret** page, copy the credentials and store them somewhere secure. For the Authorization Code grant type, Twilio generates a **Client ID**, **Client Secret**, and **Authorization URL**.
7. Select the **Got it!** checkbox and click **Finish**.

### Authorize an Authorization code application

After you create the OAuth application, authorize it to obtain an authorization code.

1. Construct the authorization URL with the following query parameters:
   ```text
   https://oauth.twilio.com/v2/authorize?client_id=CLIENT_ID&response_type=code&scope=offline_access&redirect_uri=REDIRECT_URL&state=STATE
   ```
   * Replace `CLIENT_ID` with the Client ID from your OAuth application.
   * Replace `REDIRECT_URL` with the Redirect URL configured in your OAuth application.
   * Replace `STATE` with a unique value to prevent CSRF attacks.
2. Open the authorization URL in a browser.
3. Sign in with your Twilio credentials.
   > \[!NOTE]
   >
   > The authorization page doesn't support SSO login. Use an organization admin user whose SSO is deactivated.
4. Review the requested scopes and permissions, then click **Approve access**.

After approval, you're redirected to your Redirect URL with the authorization code:

```text
REDIRECT_URL?code=AUTHORIZATION_CODE&state=STATE
```

The authorization code expires after five minutes. Use it immediately to generate access tokens using the [Token API](/docs/iam/oauth-apps/oauth-access-token).

### View or update an OAuth app

## Twilio Console

1. Log in to [Twilio Console](https://1console.twilio.com/) and navigate to [**Settings** > **Organization settings** > **Organization API access**](https://1console.twilio.com/organization/settings/oauth/apps).
2. On the **OAuth apps** page, click on the **App name** of the Authorization Code app you want to view or update.
3. On the **APPLICATION DETAILS** tab, view **Application name, Description of the application, Date created, Created by, Company name, Homepage URL, Terms of service URL** and **Redirect URL**. To update the application details, click **Edit application details** and update the details, then click **Save**.
4. On the **ACCESS SETTINGS**, view **OAuth Scopes**. You can update the **OAuth scopes**.
5. On the **Credentials** tab, view the **Client ID** and **Authorization URL** with the ability to rotate Client Secret.

## Legacy Console

1. In the Legacy Console, go to [**Twilio Admin**](https://admin.twilio.com/) and navigate to [**Applications** > **OAuth apps**](https://admin.twilio.com/applications/oauth).
2. On the **OAuth apps** page, click on the **App name** of the Authorization Code app you want to view or update.
3. On the OAuth apps detail page view **Application name, Description of the application, Date created, Created by, Company name, Homepage URL, Terms of service URL, Redirect URL, Scopes, Client ID** and **Authorization URL**.
4. Click **Save** to update the app or **Cancel** to go back to the OAuth apps list page.

### View Authorized apps

When the Authorization Code OAuth app is authorized and the authorization code is generated, the OAuth app appears under **Authorized apps**.

## Twilio Console

1. Log in to [Twilio Console](https://1console.twilio.com/) and navigate to [**Settings** > **Organization settings** > **Organization API access**](https://1console.twilio.com/organization/settings/oauth/apps).
2. Click **AUTHORIZED APPLICATIONS** to view all the Authorized apps along with the name of the user who authorized, in the **Authorized by** column.

## Legacy Console

1. In the Legacy Console, go to [**Twilio Admin**](https://admin.twilio.com/) and navigate to [**Applications** > **Authorized apps**](https://admin.twilio.com/applications/authorized-apps).
2. View all the Authorized apps along with the name of the user who authorized under **Authorized by** column.

### Revoke access of an Authorized app

## Twilio Console

1. Log in to [Twilio Console](https://1console.twilio.com/) and navigate to [**Settings** > **Organization settings** > **Organization API access**](https://1console.twilio.com/organization/settings/oauth/apps).
2. Click on **AUTHORIZED APPLICATIONS** to view all the Authorized apps.
3. Click the **Revoke** button next to the Authorized app to revoke access.

## Legacy Console

1. In the Legacy Console, go to [**Twilio Admin**](https://admin.twilio.com/) and navigate to [**Applications** > **Authorized apps**](https://admin.twilio.com/applications/authorized-apps).
2. View all the Authorized apps along with the name of the user who authorized under **Authorized by** column.
3. Click the **Revoke** button next to the Authorized app to revoke access.

### Delete an OAuth app

## Twilio Console

1. Log in to [Twilio Console](https://1console.twilio.com/) and navigate to [**Settings** > **Organization settings** > **Organization API access**](https://1console.twilio.com/organization/settings/oauth/apps).
2. In the **Action** column of the OAuth app you want to delete, click **Delete**.
3. In the pop-up, click **Delete**.

## Legacy Console

1. In the Legacy Console, go to [**Twilio Admin**](https://admin.twilio.com/) and navigate to [**Applications** > **OAuth apps**](https://admin.twilio.com/applications/oauth).
2. On the **OAuth apps** page, click on **Delete** under Actions.
3. In the pop-up, click **Delete** to confirm deletion.

> \[!NOTE]
>
> When you delete an Authorization Code OAuth app, its access is revoked immediately and any active access tokens become invalid.

## Scopes/Permissions available for Organization OAuth apps

Here are the list of Scopes & Permissions and Organization API endpoints associated with them:

| Scopes / Permissions    | Method | API Endpoints                                                     | API doc                                                      |
| ----------------------- | ------ | ----------------------------------------------------------------- | ------------------------------------------------------------ |
| managed-users/read      | GET    | `https://iam.twilio.com/scim/v2/Users/sid<US>`                    | [API Doc](/docs/iam/scim/api-reference)                      |
| managed-users/list      | GET    | `https://iam.twilio.com/scim/v2/Users`                            | [API Doc](/docs/iam/scim/api-reference)                      |
| managed-users/create    | POST   | `https://iam.twilio.com/scim/v2/Users`                            | [API Doc](/docs/iam/scim/api-reference)                      |
| managed-users/update    | PUT    | `https://iam.twilio.com/scim/v2/Users/sid<US>`                    | [API Doc](/docs/iam/scim/api-reference)                      |
| managed-users/delete    | DELETE | `https://iam.twilio.com/scim/v2/Users/sid<US>`                    | [API Doc](/docs/iam/scim/api-reference)                      |
| role-assignments/list   | GET    | `https://iam.twilio.com/v2/Organizations/RoleAssignments`         | [API Doc](/docs/iam/access-control/role-assignment-resource) |
| role-assignments/create | POST   | `https://iam.twilio.com/v2/Organizations/RoleAssignments`         | [API Doc](/docs/iam/access-control/role-assignment-resource) |
| role-assignments/delete | DELETE | `https://iam.twilio.com/v2/Organizations/RoleAssignments/sid<IY>` | [API Doc](/docs/iam/access-control/role-assignment-resource) |
| roles/list              | GET    | `https://iam.twilio.com/v2/Organizations/Roles`                   | [API Doc](/docs/iam/access-control/role-resource)            |