Server-side web applications - Authorization Code Grant

In order to access the Aventus Platform API from a web application, you’ll need to implement the Authorization Code OAuth2 flow.

🚧

This authorization flow should only be used in scenarios where the client secret can be securely stored on the server side. Single Page Applications should not use this authorization flow as the client secret cannot be securely stored.

This authorization flow is a two-step process

  • Request an authorization code
  • Exchange the authorization code for an access token

1. Authorize the user

Redirect the user to the /authorize endpoint. The user will authenticate and grant your application access for the requested scopes

https://auth.homelyfe.com/authorize?
audience=API_IDENTIFIER&
scope=SCOPE&
response_type=code&
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
state=STATE

Request Parameters

Parameter

Value

audience

The API you are requesting access for (API Base URL)

scope

The scopes that you want to request authorization for. Each scope must be separated by a space.

response_type

code

client_id

Your application’s Client ID (provided by Aventus when you registered your application)

state

A randomly generated unique value included in the request that is also returned in the token response, this is used to prevent cross-site request forgery attacks.

redirect_uri

The redirect_uri of your application, where authentication responses will be sent to.

The redirect uri must exactly match one of the callback URLs provided when registering your application

Response

At this point, the user is asked to enter their credentials and consent to the permissions (scopes) requested by your application. After the user has grants consent to your application, Aventus sends a response to the redirect_uri with an authorization_code in the query string.

https://YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE

Parameter

Description

code

The authorization code that your application requested. Your application can use this authorization code to request an access token for the API.

state

The state parameter sent in the response should be the same value sent in the request. It is good practice to verify that the state values in the request and response are identical.

2. Exchange the authorization code for an access token

Using the authorization code (code) from the previous step, send a POST request to the /token endpoint

using (var client = new HttpClient())
{
  client.BaseAddress = new Uri("https://auth.homelyfe.com/");
  var bodyContent = new StringContent(@"{""grant_type"":""authorization_code"",""client_id"":""YOUR_CLIENT_ID"",""client_secret"":""YOUR_CLIENT_SECRET"",""code"":""YOUR_AUTHORIZATION_CODE"",""redirect_uri"":""YOUR_CALLBACK_URL""}", Encoding.UTF8, "application/json");
  var response = await client.PostAsync("oauth/token", bodyContent);
}

Request Parameters

Parameter

Description

grant_type

authorization_code

client_id

Your application’s Client ID (provided by Aventus when you registered your application)

client_secret

Your application’s client secret (provided by Aventus when you registered your application)

code

The authorization code that you received in step 1

redirect_uri

The redirect URL sent in the /authorize request in step 1. It must be identical to what was sent in the /authorize request.

Response

{
  "access_token":"",
  "token_type":"Bearer",
  "expires_in":86400
}

Parameter

Description

access_token

The requested access token as a signed JSON Web Token (JWT). Your application can use this token to access the Aventus Platform API.

token_type

Indicates the token type. The only token type supported by the Aventus Platform is Bearer

expires_in

How long the access token is valid (in seconds)

Error Response

Parameter

Description

error

OAuth error code

error_description

Description of the error