Generating an authorization request

Last updated: 2023-10-25Contributors
Edit this page

The OAuth auth token flow is often initiated by sending a user to a URL to login to the remote service, authorize the application, and return the user to the remote service to complete the handshake and authorization process. The following document describes how to construct this authorization URL in order to begin the OAuth flow.

Building the Authorization Request URL

An authorization request URL will vary depending upon what environment you are are building your app with in.

Environment Base URL
Sandbox https://platform.devtest.ringcentral.com/restapi/oauth/authorize
Production https://platform.ringcentral.com/restapi/oauth/authorize

Authorization request parameters

The parameters that are attached to the URL you build are determined by the OAuth 2.0 specification itself, but guidance is provided below on what the value of these parameters should be for RingCentral.

Parameter Discussion
response_type This should always be equal to code.
client_id The client ID of your application. Each application is provisioned a different client ID for sandbox and production. Be sure the client ID you provide corresponds with the environment you are building your URL for.
redirect_uri The URI to redirect a user back to when the authorization phase is complete. For security purposes, the URL you specify here must match one of the Redirect URLs you have registered for this corresponding application.
state Per the OAuth specification, RingCentral ignores any value passed in this parameter and echoes it back as a parameter to the specified redirect URI. Developers can use this parameter to facilitate the correlation of a RingCentral user with the user ID within their service.
code_challenge This is a string generated by the developer to facilitate an extra layer of security to verify the authenticity of an authorization request. See our documentation on auth code flow using PKCE.
code_challenge_method Used in conjunction with the code_challenge parameter.
brand_id This is a proprietary, RingCentral-specific parameter used to control which partner's brand is displayed on the login screen hosted by RingCentral.
display This is a proprietary, RingCentral-specific parameter used to determine the modality used to display the login screen the user will be presented with. Allowable values include: page (default), popup, touch, and mobile.

Example URL

The following example URL shows a minimal URL used to initiate the authorization process in production:

https://platform.ringcentral.com/restapi/oauth/authorize?response_type=code&client_id=<CLIENTID>&redirect_uri=<URL (escaped)>