Mobile & Desktop apps - Authorization Code Grant (PKCE)

In order to access the Aventus Platform API from a mobile app, you’ll need to implement the Authorization Code using Proof Key for Code Exchange (PKCE) OAuth2 flow.

This authorization flow is a two-step process,

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

1. Generate a code_verifier

A code_verifier is a randomly generated token of 128 bytes that is Base64 URL encoded

2. Generate a code_challenge

The only code challenge method supported by the Aventus Platform is S256.

2.1 Generate a SHA256 hash of the code_verifier

2.2 Base64 URL Encode the sha256 hash from the previous step
BASE64URL-ENCODE(SHA256(code_verifier))

3. 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&
code_challenge=CODE_CHALLENGE&
code_challenge_method=S256

Request Parameters

Parameter	Description
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
code_challenge	The code_challenge generated in step 2
code_challenge_method	`S256` The only code challenge method supported by the Aventus Platform is S256

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://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.

4. 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"",""code_verifier"":""YOUR_GENERATED_CODE_VERIFIER"",""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)
code_verifier	The random key generated in step 1 that was used to generate the code_challenge
code	The authorization code that you received in step 3
redirect_uri	The redirect URL sent in the `/authorize` request in step 3. 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