Connecting Apps with ReAI using OAuth2

Integrating your application with ReAI through OAuth2 Authorization Code Flow provides secure, user-authorized access to ReAI data. This guide covers the essential implementation steps.

OAuth2 Flow Overview

The complete authorization flow involves several steps between your app, ReAI, and the user:

1. App Installation: Admin creates and installs the app in ReAI
2. User Authorization: User clicks to open the app and is redirected to authorize
3. Token Exchange: App receives authorization code and exchanges it for access tokens
4. API Access: App uses access token to call ReAI APIs
5. Auto Refresh: App automatically refreshes expired tokens

App Lifecycle

Create App

First, you need to login at app.reai.no and go to Settings → Create Apps

When creating an application in ReAI, you need to fill in the following information:

After you click create, the app will be created and displayed here:

And detail when you click it:

Status options:

• INTERNAL: Visible only to your tenant
• REVIEW: Under review for publication
• PUBLISHED: Public, visible to all tenants

You should press publish your app so that it can be displayed on the store.

Install App

You can install app at App Store → select app → click Install

Note: Only apps with a PUBLISHED status will be displayed on the App Store.

When a tenant installs your app, ReAI automatically creates OAuth credentials:

• client_id: cli_xxxxxxxxx
• client_secret: random string
• Redirect URIs from your app URL
• Granted scopes from app definition

Open App

The app will appear here:

When you open your app, ReAI automatically creates OAuth credentials:

• client_id: cli_xxxxxxxxx
• client_secret: random string
• Redirect URIs from your app URL
• Granted scopes from app definition

ReAI then redirects to your app with credentials:

https://your-app.com/?client_id=xxx&client_secret=yyy&scope=employee:read

Implementation Steps

Step 1: Receive Credentials

Your app receives credentials from URL parameters and you should save it:

const params = new URLSearchParams(window.location.search);
const clientId = params.get('client_id');
const clientSecret = params.get('client_secret');
const scope = params.get('scope');
localStorage.setItem('reai_client_id', clientId);
localStorage.setItem('reai_client_secret', clientSecret);

Step 2: Redirect to Authorization

Redirect users to ReAI’s authorization endpoint:

const authorizeUrl =
  `https://app.reai.no/oauth2/authorize` +
  `?response_type=code` +
  `&client_id=${clientId}` +
  `&redirect_uri=${encodeURIComponent('https://your-app-url/')}` +
  `&scope=${encodeURIComponent(scope)}`;

window.location.href = authorizeUrl;

Step 3: Exchange Code for Tokens

After user authorization, ReAI redirects back with a code. Exchange it for tokens:

POST https://app.reai.no/oauth2/token
Authorization: Basic base64(clientId:clientSecret)
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=ABC123
&redirect_uri=http://your-app-url

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "f4K...",
  "expires_in": 7200,
  "token_type": "Bearer"
}

Step 4: Use Access Token

Example: Call ReAI APIs with the access token:

fetch('https://app.reai.no/api/employees', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

Step 5: Auto-Refresh Expired Tokens

Check token expiration before each request:

function isTokenExpired(token) {
  const payload = JSON.parse(atob(token.split('.')[1]));
  return Date.now() >= payload.exp * 1000;
}

Refresh when expired:

POST https://app.reai.no/oauth2/token
Authorization: Basic base64(clientId:clientSecret)
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=f4K...

Token Lifecycle

• Access Token: Expires after 2 hours
• Refresh Token: Expires after 30 days

Your app should automatically refresh access tokens. When the refresh token expires, restart the OAuth flow.

Configuration Example

Backend configuration (application.yml):

reai:
  oauth2:
    authorization-endpoint: https://app.reai.no/oauth2/authorize
    token-endpoint: https://app.reai.no/oauth2/token
    redirect-uri: https://your-app-url/authorized

Troubleshooting

Invalid redirect_uri: Ensure your redirect URI exactly matches what’s registered in ReAI

Token expired: Implement automatic refresh logic before tokens expire

Invalid client credentials: Verify client_id and client_secret are correct

Insufficient scope: Request all necessary scopes when creating the app

Summary

OAuth2 Authorization Code Flow provides secure integration between your app and ReAI:

1. User authorizes your app through ReAI
2. Your app exchanges authorization code for tokens
3. Use access tokens to call ReAI APIs
4. Automatically refresh tokens when expired
5. Restart OAuth flow when refresh token expires

This implementation ensures secure, user-authorized access to ReAI data without exposing sensitive credentials.