Set up OAuth for SCIM

You must be an Organization Owner or Organization Admin to create and authorize OAuth applications.

1. Sign in to the Twilio Console.
2. Click Admin in the top-right corner to open the Admin Center.
3. Go to Applications > OAuth apps.
4. Click Create OAuth app.
5. Select Authorization code as the grant type.
6. Enter the application details:
   • For Application name, enter a name for your OAuth app.
   • For Company Name, enter your company name.
   • For Redirect URL enter an identity provider URL where Twilio should redirect the user after they authorize your app. For example, https://example.com/token.
   • For Scopes and Permissions, select all managed-users scopes.
7. Click Save.

After you save your configuration, Twilio generates the Client ID, Client Secret, and Authorization URL. Copy these values and store the Client Secret securely. Twilio shows the Client Secret only once.

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

1. Construct the authorization URL with the following query parameters:
   Copy code block

   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.
   (information)

   Info

   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:

REDIRECT_URL?code=AUTHORIZATION_CODE&state=STATE

The authorization code expires after five minutes. Use it immediately to generate access tokens.

You can exchange the authorization code for access and refresh tokens.

1
curl --location 'https://oauth.twilio.com/v2/token' \
2
--header 'Content-Type: application/x-www-form-urlencoded' \
3
--data-urlencode 'client_id=CLIENT_ID' \
4
--data-urlencode 'client_secret=CLIENT_SECRET' \
5
--data-urlencode 'grant_type=authorization_code' \
6
--data-urlencode 'code=AUTHORIZATION_CODE' \
7
--data-urlencode 'redirect_uri=REDIRECT_URL'

Replace the following placeholders in the above cURL request:

• Replace CLIENT_ID with your OAuth application's Client ID.
• Replace CLIENT_SECRET with your OAuth application's Client Secret.
• Replace AUTHORIZATION_CODE with the authorization code from the previous step.
• Replace REDIRECT_URL with your configured Redirect URL.

1
{
2
    "access_token": "ACCESS_TOKEN",
3
    "id_token": null,
4
    "token_type": "Bearer",
5
    "expires_in": 3600,
6
    "refresh_token": "REFRESH_TOKEN"
7
}

This response includes the following values:

• ACCESS_TOKEN: the access token to authenticate SCIM API requests.
• REFRESH_TOKEN: the refresh token to obtain new access tokens.

The access token is a JSON Web Token (JWT) that expires after one hour. Use the refresh token to obtain new access tokens without reauthorizing.

Include the access token in the Authorization header for SCIM API requests:

1
curl --location 'https://iam.twilio.com/scim/v2/Users' \
2
--header 'Authorization: Bearer ACCESS_TOKEN'

Replace ACCESS_TOKEN with your access token.

After setting up OAuth, you can explore the following resources:

• SCIM API reference: View the complete API reference for user management endpoints.
• Okta integration: Configure SCIM provisioning with Okta as your identity provider.