The Authorization Code Grant is the most common authorization flow in OAuth2. It is a three-legged process which can be used for best security with backends which support keeping client credentials (client IDs and secrets) confidential.

The flow works like this in short words:

  1. The application which needs access to an API redirects the user agent (usually the browser) to the authorization page of the Authorization Server.
  2. The Authorization Server verifies the identity of the end user (by whichever suitable means), checks the client ID of the calling application, and if everything is fine, issues a so-called "Authorization Code".
  3. The Authorization Server redirects (302) back to the calling application, giving the authorization code back as a query parameter (?code=(authorization code)).
  4. The application now uses the authorization code together with its client credentials (id and secret) to retrieve an actual access and refresh token.
  5. The application can now use the API with the returned access token.

Getting an Authorization Code

The calling application must redirect to the correct Authorization Server /authorize end point. The URL of this endpoint depends on the authentication method, and on the API. The URL is displayed for each supported Authentication Method at the top of each API page. method id)/api/(api id)/authorize?client_id=(your client id)&redirect_uri=(redirect URI of your application)&response_type=code&scope=(space separated list of scopes)

All parameteters except the scope (depending on the API) are mandatory. The correct URL for valid combinations of API and Authentication Method can be seen on the API page.

Note the use of response_type=code, as opposed to response_type=token for the Implicit Grant.

The Authorization Server will now verify the user's identity, and also check whether the application is either implicitly (because it is a trusted application/subscription), or explicitly allowed to access the API on behalf of the user. In case the user has not yet consented to the application accessing the API on behalf of the user, wicked will ask the user to grant access to the application, so that it can access the API on behalf of the user.

If the end user's identity could be verified, the Authorization Server will craft an authorization code which is passed back to your application with a 302 redirect, giving the authorization code as a query parameter: code)

Getting an Access Token

This authorization code can now be used by your application, which has to call the Token endpoint, passing the authorization code, and the application's client credentials, to create an access token (and a refresh token). An example request using curl would look as follows:

curl -X POST -H 'Content-Type: application/json' -d '{"grant_type=authorization_code","client_id":"(your client id)","client_secret":"(your client secret)","code":"(authorization code)"}' method id)/api/(api id)/token

In case of a success, the token endpoint returns a JSON structure which contains an access token and a refresh token:

  "access_token": "(access token)",
  "refresh_token": "(refresh token)",
  "token_type": "bearer",
  "expires_in": 3600

The token expiration depends on the API configuration and can vary between APIs.

Accessing the API

With the returned access token, you may now access the API using the token as a bearer token:

curl -H 'Authorization: Bearer (access token)' endpoint)

The actual API endpoint is also displayed on the API's page.

Refreshing the Access Token

Your application can refresh the access token using a specific call to the same /token end point as before. Using curl syntax, the call will look like this:

curl -X POST -H 'Content-Type: application/json' -d '{"grant_type=refresh_token","client_id":"(your client id)","client_secret":"(your client secret)","refresh_token":"(refresh token)"}' method id)/api/(api id)/token

If successful, the Authorization Server will return a new access token and a new refresh token.

Important: After refreshing the access token using the refresh token, the refresh token which was used for this, is no longer valid. You must then use the new refresh token.