Authorization code grant flow quick start

If you are building a server-side web application that is capable of securely storing secrets, you may want to use the authorization code flow to control access to it. This quick guide procedure will help you start using the authorization code grant flow as soon as possible.

Before you begin

  1. Configure OAuth scopes for resource and methods in your registered API. See Configure OAuth 2.0 scopes.
  2. Register at least one identity provider to authenticate resource owners. See Register an identity provider.
  3. Set up your app in OAuth Management in Control Center. See Register a client app.

How to

  1. Start the authorization grant flow by navigating the user agent to the URL that follows this pattern:<client-id>&scope=<scope-1>%20<scope-2>&response_type=code&redirect_uri=<redirect-uri>&state=<your-xsrf-token>
    Note the parameters in the request:
    The client identifier of the app that you registered in OAuth Management.
    The scopes that you configured in API Definitions.
    Information for the Authorization Server to initiate a specific grant flow. For the authorization code grant flow, its value is code.
    The location where the Authorization Server sends the user agent after the user approves the request. It must match one of the Redirect URIs you specified when registering your client app.
    An XSRF token reproduced by the Authorization Server when redirecting the user-agent back to the client. It is an arbitrary alphanumeric used to help prevent cross-site request forgery.
    The Authorization Server redirects the user to the specified redirect_uri. The URL will look similar to this one:


  2. Exchange the <authorization-code> by passing it to the Authorization Server:
    POST HTTP/1.1 
    Authorization: Basic <client-id>:<client-secret> 
    Content-Type: application/x-www-form-urlencoded 
    Note the parameters in the request:
    Information which authorization grant flow you are using. For the authorization grant flow, it's auhtorization_code.
    The URI used to get the authorization code.
    The authorization code you got from the authorization endpoint in step 1.

What you should see

If the request for an access token is valid, you will see a response that follows this pattern:

HTTP/1.1 200
Content-Type: application/json

    "access_token": <access-token>,
    "token_type" : "Bearer",
    "refresh_token" : <refresh-token>,
    "expires_in" : <expiration-time-in-seconds>,
    "scope" : <granted-scopes>
Note the properties of the response:
The access token issued by the Authorization Server.
The type of token. Typically, it is a string Bearer.
The refresh token that the client app can use after the access token expires to get another access token.
The time in seconds that the access token is valid for.
The scopes granted to the client app.

Next steps

You can renew your access token after it expires. See Refreshing access tokens.