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:
    https://oauth.akamai.com/v1/authorize?client_id=<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:
    client-id
    The client identifier of the app that you registered in OAuth Management.
    scope
    The scopes that you configured in API Definitions.
    response_type
    Information for the Authorization Server to initiate a specific grant flow. For the authorization code grant flow, its value is code.
    redirect_uri
    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.
    state
    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:

    <redirect-uri>?code=<authorization-code>&state=<your-xsrf-token>

  2. Exchange the <authorization-code> by passing it to the Authorization Server:
    POST https://oauth.akamai.com/v1/token HTTP/1.1 
    Authorization: Basic <client-id>:<client-secret> 
    Content-Type: application/x-www-form-urlencoded 
    
    grant_type=authorization_code&redirect_uri=<redirect-uri>&code=<authorization-code>
    Note the parameters in the request:
    grant_type
    Information which authorization grant flow you are using. For the authorization grant flow, it's auhtorization_code.
    redirect_uri
    The URI used to get the authorization code.
    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:
access_token
The access token issued by the Authorization Server.
token_type
The type of token. Typically, it is a string Bearer.
refresh_token
The refresh token that the client app can use after the access token expires to get another access token.
expires_in
The time in seconds that the access token is valid for.
scope
The scopes granted to the client app.

Next steps

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