> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-platform/6/admin-essentials/integrations/auth/oauth2/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Configure OAuth2 for integrations > How to configure OAuth2 for integrations in Itential Platform, including basic setup, refresh tokens, retrieving access tokens, and troubleshooting. The OAuth 2.0 Authorization Code Grant Flow is a secure method for an application to get authorized access to protected resources. This process involves exchanging an authorization code for an access token, which acts as a key to the protected resources. In Itential, this flow lets you configure integrations that securely connect to services using OAuth 2.0. Platform automatically manages the entire exchange process, from getting the initial authorization code to automatically refreshing the access token. ## Configure OAuth This section provides configuration examples for the most common OAuth 2.0 use cases. ## Before you begin * Obtain the client ID and secret from your OAuth provider. * Identify the authorization and token URLs for your OAuth provider. * Determine the required [scopes](https://oauth.net/2/scope/) for your integration. * Configure the redirect URI in your OAuth provider settings. ## Basic OAuth 2.0 This is the most common use case, covering the essentials of setting up a connection that requires a user's consent. #### Define your OAuth 2.0 schema In your integration's OpenAPI definition, configure the `securitySchemes` object with `type: oauth2` and `flows: authorizationCode`. #### Add URLs and scopes Specify the `authorizationUrl` (where users grant permission) and the `tokenUrl` (where Itential exchanges the code for a token). List the available scopes that your provider offers. ```json { "components": { "securitySchemes": { "OAuth2Security": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://account.box.com/api/oauth2/authorize", "scopes": { "root_readonly": "Read all files and folders in Box", "root_readwrite": "Read and write all files and folders in Box" }, "tokenUrl": "https://api.box.com/oauth2/token" } } } } } } ``` #### Configure the integration instance In Itential's Admin Essentials, provide the `client_id` and `client_secret` from your OAuth 2.0 provider. #### Set the redirect URI On your OAuth 2.0 provider's side, configure the redirect URI to `{{iap}}/admin/oauth/`. For example, if your Platform instance is at `https://itential.iap.com/`, the redirect URI is `https://itential.iap.com/admin/oauth/`. Don't forget the trailing slash. #### Specify scopes (optional) Set the scope string in the integration instance to request a subset of permissions. Use a space-separated string, like `root_readonly manage_app_users`. ## OAuth 2.0 with refresh tokens This scenario is automatically handled by Platform. If your provider sends a refresh token along with the access token, Itential stores it and uses it to automatically renew the session when the access token expires. No extra configuration is needed on the Itential side. Follow the same steps as the basic setup. Ensure that your token URL is correct and that the OAuth 2.0 provider is configured to issue refresh tokens. **Automatic reauthentication:** If your authentication server provides a refresh token, Itential automatically handles reauthentication using your configured token URL. ## OAuth 2.0 with custom headers or parameters If your OAuth 2.0 provider requires custom headers or parameters during the token exchange, you may need to modify the OpenAPI specification. Contact Itential Support for advanced configuration options. ## Authorization code flow schema An example import of an integration model with an `authorizationCode` type in its `securitySchemes`: ```json { ... "components": { "securitySchemes": { "OAuth2Security": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://account.box.com/api/oauth2/authorize", "scopes": { "manage_app_users": "Provision and manage app users", "manage_data_retention": "Manage data retention polices", "manage_enterprise_properties": "Manage enterprise properties", "manage_groups": "Manage an enterprise's groups", "manage_legal_hold": "Manage Legal Holds", "manage_managed_users": "Provision and manage managed users", "manage_webhook": "Create webhooks programmatically through the API", "root_readonly": "Read all files and folders stored in Box", "root_readwrite": "Read and write all files and folders stored in Box" }, "tokenUrl": "https://api.box.com/oauth2/token" } } } } } } ``` For the Auth Code Flow, the given `type` of the scheme must be `oauth2` and it must have an `authorizationCode` object within the `flows` object. The `authorizationUrl` is the URL the user will be sent to in order to authorize the grant (i.e., retrieve the auth code). That URL will then redirect the user back to Platform with an authorization code, which Platform automatically exchanges at the `tokenUrl` for an access token. The `scopes` is an enumerated list of `scope_name: description` of all scopes the OAuth provider offers, from which you may choose a subset for the access token. From Admin Essentials, you can declare this subset in the configuration of the integration instance. ## Set up the integration instance To configure the integration instance, provide the `client_id` and `client_secret` from your OAuth2 provider. Make sure you supply the OAuth provider with the `redirect_uri` of `{{iap}}/admin/oauth/`. For example, if Platform is at `https://itential.iap.com/`, set the `redirect_uri` as `https://itential.iap.com/admin/oauth/` (don't forget the trailing `/`). Optionally, specify your desired scopes of the access token in the `scope` as a space-separated string. Using the [schema model](#authorization-code-flow-schema) above, a valid `scope` setting could be `manage_app_users manage_data_retention manage_webhook`. Once you have configured your integration instance, click **Save** to retain your changes. ![](/_fern-img/d4407eafbeb27e9e04fe1d30e130a6c21709a4d3db7a91083f17604fa66b4ab7.webp) ## Retrieve an access token To obtain an access token, click the **Get Access Token** button, which sends you to the OAuth2 provider you are interfacing with to "Approve Access." You must supply the OAuth2 provider with the redirect URL of `{{iap}}/admin/oauth/`. The example below uses the BoxDev OAuth2 provider, but this works for any OAuth2 provider. ![](/_fern-img/eea4ecec61759d89fe05953e8a957e2e91f991152fab3e7939d9f86a8299b657.webp)![](/_fern-img/7405e823da9d4f709e963b57728dfa9b3d1f10072fb856ac88e903fd71affef7.webp) Once access is granted, you are redirected back to Itential Platform and a success notification confirms the access token was retrieved. ![](/_fern-img/941730a65752c63f0c8e95503241c82f9a80656f338f550fe8d15964b2b5f4e9.webp) ## Troubleshooting If you fail to retrieve the access token, there are a few likely reasons: * **Invalid `client_id` or `client_secret`**: Double-check with your OAuth provider that these values are correct. * **Invalid `scope`**: If you attempt to request a scope that does not exist, the OAuth provider may outright refuse your request. * **Invalid `token_url`**: You may change the `token_url` for a given instance after creation. If it points to a different URL than expected, the access token request will fail. ## Related topics * [Auth0 Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) * [OAuth Client ID and Secret](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) * [IETF RFC 6749 Authorization Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1) > How to configure OAuth2 for integrations in Itential Platform, including basic setup, refresh tokens, retrieving access tokens, and troubleshooting.