Authorization Code Flow with PKCE

Use for

• Mobile Applications

• Native Applications

Following process describes how to obtain an user's authorization to interact with the Loom AI API on the user's behalf using the OAuth2 Authorization Code Flow with Proof Key for Code Exchange.

1. Generate Code Challenge & Verifier

PKCE is an extension for the Authorization Code Flow protecting against 3rd parties hijacking your application's authorization request by validating that the token exchange request is originating from the same client that initiated authorization.

This works by generating a secret (code verifier) and appending a hash thereof (code challenge) to the authorization request. The code verifier is subsequently being appended to the token exchange request, allowing the authorization server to compare it to the previously received code challenge.

Now lets walk through the steps. Start by generating the code verifier and hash it to obtain a code challenge.

JavaScript

const crypto = require('crypto');


function base64URLEncode(str) {
    return str.toString('base64').
        replace(/\+/g, '-').
        replace(/\//g, '_').
        replace(/=/g, '');
}

function sha256(buffer) {
    return crypto.createHash('sha256').
        update(buffer).
        digest();
}


const CODE_VERIFIER = base64URLEncode(crypto.randomBytes(32));
const CODE_CHALLENGE = base64URLEncode(sha256(CODE_VERIFIER));

2. User Authentication & Request Authorization

Redirect the user to following parameterized URL to authenticate the user and request authorization for your application to interact with the Loom AI API on the user's behalf.

https://auth.loomai.com/authorize?
  response_type=code&
  audience=https%3A%2F%2Fapi.loomai.com%2F&
  client_id={CLIENT_ID}&
  code_challenge_method=S256&
  code_challenge={CODE_CHALLENGE}&
  redirect_uri={REDIRECT_URI}&
  scope={SCOPE}&
  state={STATE}

Parameter	Description
response_type	Set to code.
audience	Set to https://api.loomai.com/(url-encoded).
client_id	Your application's Client ID.
code_challenge_method	Set to S256 (SHA-256).
code_challenge	Previously generated code challenge.
redirect_uri	The URL to which the user will be redirected after authorization has been completed (url-encoded). The authorization code will be appended to the url using the query parameter code. This url needs to be added to the callback urls when registering your client application.
scope	Whiite-space separated list of scopes you are requesting authorization for. Please refer to Authorization Scopes for more details.
state	A random alphanumeric string your client application adds to the request. The value will be included when redirecting back to your application. This is used to prevent CSRF attacks.

Request

<a href="https://auth.loomai.com/authorize?
    response_type=code&
    audience=https%3A%2F%2Fapi.loomai.com%2F&
    client_id={CLIENT_ID}&
    code_challenge_method=S256&
    code_challenge={CODE_CHALLENGE}&
    redirect_uri=https%3A%2F%2Fapp.domain.tld%2Foauth%2Fcallback&
    scope=read:avatars%20write:avatars&
    state=0xdeadbeef">
    Sign In
</a>

Response

On success, you will receive a HTTP 302 response redirecting to your specified redirect_uri with an url query string that contains the authorization result. Specifically the authorization code required to obtain an access token as well as your state parameter.

If authorization failed or has been denied by the user, the query string will contain an error parameter with further details instead.

HTTP/1.1 302 Found
Location: https://app.domain.tld/oauth/callback?
    code={AUTHORIZATION_CODE}&
    state=0xdeadbeef

3. Exchange Authorization Code for API Access Token

The authorization code obtained in previous step can now be exchanged for an access token to authorize requests of your application to the Loom AI API.

Request

curl --request POST \
  --url 'https://auth.loomai.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data audience=https://api.loomai.com/ \
  --data client_id={CLIENT_ID} \
  --data code={AUTHORIZATION_CODE} \
  --data code_verifier={CODE_VERIFIER} \
  --data redirect_uri={REDIRECT_URI}

Parameter	Description
grant_type	Set to authorization_code.
audience	Set to https://api.loomai.com/.
client_id	Your application's Client ID.
code	The authorization code obtained in previous step.
code_verifier	Previously generated code verifier.
redirect_uri	Must match theredirect_uriused in previous step (urlencoded).

Response

If all parameters are valid, you will receive a HTTP 200 response with a JSON payload containing an access_token which you can use to authorize your application's requests to the Loom AI API, a refresh_token if you included scope offline_access in previous step as well as token_type and expiry. The access token will be valid for the amount of seconds stated by expiry. Afterwards your application will either need to re-request authorization, or renew the access token if it received a refresh token.

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "token_type": "Bearer",
  "expiry": 3600
}