OAuth Authentication

At a glance

Ontologie supports the OAuth2 protocol with PKCE (Proof Key for Code Exchange) for applications that require authentication on behalf of a user. This flow is recommended for frontend and mobile applications.

When to use OAuth?

Method	Use case
API Key	Scripts, automations, server-to-server integrations
OAuth2 PKCE	Frontend applications, mobile applications, integrations that act on behalf of a user

OAuth is required when:

Your application needs to access a specific user's data
You cannot store a secret on the client side (frontend application)
You want the user to explicitly authorize access

OAuth2 PKCE flow

Step 1: Generate the code verifier and challenge

Your application generates a random code_verifier and computes the corresponding code_challenge:

// Generer un code verifier aleatoire
function generateCodeVerifier(): string {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return btoa(String.fromCharCode(...array))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

// Calculer le code challenge (SHA-256)
async function generateCodeChallenge(verifier: string): Promise<string> {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return btoa(String.fromCharCode(...new Uint8Array(hash)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

Step 2: Redirect the user

Redirect the user to the authorization page:

https://auth.ontologie-growthsystemes.com/authorize?
  response_type=code
  &client_id=VOTRE_CLIENT_ID
  &redirect_uri=https://votre-app.com/callback
  &scope=read:nodes write:nodes
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE

Parameter	Description
`client_id`	Your application identifier (obtained during registration)
`redirect_uri`	Return URL after authorization (must match the registered one)
`scope`	Requested permissions, separated by spaces
`code_challenge`	SHA-256 hash of the code verifier
`state`	Random value to protect against CSRF attacks

Step 3: Exchange the code for a token

After authorization, the user is redirected to your redirect_uri with a code:

const response = await fetch('https://auth.ontologie-growthsystemes.com/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: 'CODE_RECU',
    redirect_uri: 'https://votre-app.com/callback',
    client_id: 'VOTRE_CLIENT_ID',
    code_verifier: 'CODE_VERIFIER_ORIGINAL',
  }),
});

const { access_token, refresh_token, expires_in } = await response.json();

Step 4: Use the token

Include the token in your API requests:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "x-workspace-id: WORKSPACE_ID" \
     "https://api.ontologie-growthsystemes.com/api/queries/nodes"

Step 5: Refresh the token

When the token expires, use the refresh token:

const response = await fetch('https://auth.ontologie-growthsystemes.com/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'refresh_token',
    refresh_token: 'VOTRE_REFRESH_TOKEN',
    client_id: 'VOTRE_CLIENT_ID',
  }),
});

OAuth scopes

The available scopes are identical to those of API keys:

Scope	Description
`read:nodes`	Read entities
`write:nodes`	Create and modify entities
`read:edges`	Read relations
`write:edges`	Create and modify relations
`read:livedata`	Read Live Data sources
`write:livedata`	Manage Live Data sources

For the full list, see Permissions.

Security

Practice	Description
Store tokens securely	Use the browser's secure storage (not localStorage)
Validate the state parameter	Compare the returned state with the one sent
Always use PKCE	Never transmit the code verifier in the URL
Token lifetime	Access token: 1 hour. Refresh token: 30 days
Revocation	Revoke tokens via the `/revoke` endpoint when a user logs out

With the SDK

The @ontologie/oauth package simplifies the OAuth flow:

import { createOAuthClient } from '@ontologie/oauth';

const oauth = createOAuthClient({
  clientId: 'VOTRE_CLIENT_ID',
  redirectUri: 'https://votre-app.com/callback',
  scopes: ['read:nodes', 'write:nodes'],
});

// Demarrer le flux
const authUrl = await oauth.getAuthorizationUrl();
window.location.href = authUrl;

// Callback : echanger le code
const tokens = await oauth.handleCallback(window.location.search);

Need help?

Send feedback about this page

At a glance​

When to use OAuth?​

OAuth2 PKCE flow​

Step 1: Generate the code verifier and challenge​

Step 2: Redirect the user​

Step 3: Exchange the code for a token​

Step 4: Use the token​

Step 5: Refresh the token​

OAuth scopes​

Security​

With the SDK​

See also​

Need help?​