Authorization Code Flows

Last Updated:

A server-side web application able to securely store secrets requires controlled code management. The authorization code flow is recommended.

Authorization Code Flow

  1. Your solution application connects the browser to the Fortellis Log In page for users to authenticate.
  2. The browser processes an authorization code from your Fortellis authorization server.
  3. Next, the authorization code is directed to your solution application.
  4. Your application sends this code to Fortellis and returns the access and ID tokens. A refresh token can be returned too (optional).
  5. These tokens are used by your solution to call the resource server for the user.

Request Authentication

A request authenticates the user and returns tokens with an authorization grant to the client application as part of the callback response. Refer to the example below:

https://identity.fortellis.io/oauth2/aus1p1ixy7YL8cMq02p7/v1/authorize?client_id={your_client_id}
&response_type=code&scope=openid&redirect_uri={your_redirect_uri}&state={some_state_value}

The passed parameters in the authentication are in the table below:

Parameter Description
client_id Matches the API key for your solution.
response_type=code Indicates we're using the authorization code grant type.
scope=openid The /token endpoint will return an ID token.
redirect_uri The callback location where the user-agent will be directed to with the code. This must match one of the Callback URL you specified when you registered your solution.
state An arbitrary alphanumeric string the authorization server will generate when redirecting the user-agent back to the client. It helps prevent cross-site request forgery.
 


Learn more about OAuth 2.0 API standards.

User Session

Users without an existing session are directed to the Fortellis Log In page. After sessioned users authenticate, they'll receive redirect_uri and a code like the one below:

{your_redirect_uri}/?code=P5I7mdxxdv13_JfXrCSq&state=state-296bc9a0-a2a2-4a57
-be1a-d0e2fd9bb601

The user session code is valid for 60 seconds and can be exchanged for tokens.

Exchanging the Code for Tokens

To exchange the code for access and ID tokens, pass it to your authorization server’s token endpoint. See the example below:

curl --request POST \
  --url https://identity.fortellis.io/oauth2/aus1p1ixy7YL8cMq02p7/v1/token \
  --header 'accept: application/json' \
  --header 'authorization: Basic MG9hY...' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&redirect_uri={your_redirect_uri}&code=P59yPm1_X1gxtdEOEZjn'

The following table defines the parameters that are passed in the exchange of code for tokens:

Parameter Description
grant_type The authorization_code, indicating the authorization code grant type is being used.
redirect_uri Must match the URI used to get the authorization code.
code The authorization code received from the authorize endpoint.
 

If the code is still valid, your application will receive the access and ID tokens:

{
    "access_token": "eyJhbG[...]9pDQ",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "openid",
    "id_token": "eyJhbG[...]RTM0A"
}

Authentication

The call to the token endpoint requires authentication. It's a Basic Auth digest of the API key (username) and API secret (password). Your API key and API secret are in your Fortellis developer account. This requirement is why this call is only appropriate for applications that can guarantee the protection of the client secret.