Grant - Authorization Code

The Authorization Code Grant is a two-step authentication process where a user authenticates with Genesys Cloud, then the client application is returned an authorization code. The client application uses the authorization code to make an unauthenticated API request to get an access token. The access token can then be used when making authenticated API calls. This is the most secure option and ideal for websites where API requests will be made server-side (e.g. ASP.NET or PHP) and some desktop applications where a thin client would authorize the user and pass the auth code to a back-end server to exchange for an auth token and make API requests.

Follow these steps to obtain an access token using the authorization code method. For a more concise rundown, see Quick Reference.

Navigate to the OAuth admin page (Admin > Integrations > OAuth). The Client ID for each configured OAuth client will be shown in the list. Editing the OAuth client will additionally display the grant type, client secret, and the redirect URIs. Take note of these values as they will be used in the following steps. For help creating a new OAuth client, see Create an OAuth Client.

Redirect the user's browser to the Genesys Cloud authorization server:

https://login.mypurecloud.com/oauth/authorize
?client_id=<my-client-id>
&response_type=code
&redirect_uri=<http://example.com/oauth/callback>

The user will provide their credentials to Genesys Cloud via one of the supported methods. More information on logging in: Log in, Log in using SSO

If the OAuth client has not been authorized and the user has the oauth:client:authorize permission, they will need to authorize it. More information on authorizing OAuth clients: Authorize an OAuth Client

The authorization server redirects the browser to your application at the specified redirect URI. The redirection URI includes a querystring parameter named code containing the authorization code.

http://example.com/oauth/callback?code=my-authorization-code

The authorization server may redirect the browser to your application with an error code. For more info, see OAuth Error Redirects

Make a POST request to the authorization service to exchange the authorization code for an access token. The request must contain the client ID and client secret in the base 64 encoded Authorization header. For help creating the Authorization header, see How to Use Base 64 Encoding. The authorization code obtained in the previous step must be provided as part of the form encoded body.

POST /oauth/token HTTP/1.1
Host: login.mypurecloud.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(<client_id>:<client_secret>)

grant_type=authorization_code&code=<my-authorization-code>&redirect_uri=<http://example.com/oauth/callback>

The authorization service returns a JSON response with the token, token type, token expiry time in seconds, refresh token, and an error string if an error occurred.

{
  "access_token": "token",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "my-refresh-token",
  "error": "optional-error-message"
}

For additional query string parameter options, see Additional Authorization Parameters.

Follow these guidelines for using access tokens:

• After authenticating, include a token with every API request.
• Pass the token using the HTTP Authorization header with the bearer keyword, as follows:

GET /api/v2/users/me HTTP/1.1
Host: api.mypurecloud.com
Content-Type: application/json
Authorization: Bearer token

When the access token expires, a new access token can be obtained without interacting with the user by using the refresh token. To get a new access token using this method, make a request to the authorization service to exchange the refresh token for an access token. The response will be in the same format as the original response. Applications should forget the old refresh token and remember the new one as a refresh token may only be used once and the refresh response will include a new refresh token. If this request results in an error, the application must consider the user's session invalidated and must cause the user to initiate the full authorization code flow to reauthorize the application.

POST /oauth/token HTTP/1.1
Host: login.mypurecloud.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(<client_id>:<client_secret>)

grant_type=refresh_token&refresh_token=<my-refresh-token>

For a walkthrough of the authorization code grant, see the OAuth Authorization Code Grant guide.