Authentication Guide

Quick Start

We strongly recommend using an OAuth2 or OpenID Connect library for your platform. You should be able to configure clients using the discovery with https://auth.loke.global as the issuer. This will pull config from /.well-known/openid-configuration.

Key endpoints:

  • Authorization: https://auth.loke.global/authorize
  • Token: https://auth.loke.global/token
  • JWKS: https://auth.loke.global/jwks

Authentication Flows

LOKE supports two primary authentication flows

Authorization Code

Used to authenticate users for configuration and setup tasks, including:

  • Initial application installation
  • Webhook configuration
  • Integration settings
  • User-driven organization connections

Client Credentials

Used for automated backend operations:

  • Background tasks
  • Webhook processing
  • Batch operations
  • Automated syncs

Access Control

Both authentication methods provide the same level of API access, but differ in which organizations they can access:

  • Client Tokens: Access to all organizations that have installed your add-on
  • User Tokens: Access to organizations where:
    1. The user has permissions to access the organization AND
    2. Your add-on is installed for that organization

This means a user token's access is the intersection of:

  • Organizations the authenticated user can access
  • Organizations that have installed your add-on

When using user tokens, it's recommended to show users which organizations they can access and provide a link to install your add-on for organizations where it's not yet installed:

https://auth.loke.global/install-client?client=YOUR_CLIENT_ID

Implementation

The following examples use raw fetch requests to illustrate the OAuth2 flows. In practice, we strongly encourage using an OpenID Connect library for your platform to handle token management, refresh flows, and JWT validation.

Authorization Code

// Setup your routes
app.get('/connect-loke', (req, res) => {
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: 'YOUR_CLIENT_ID',
    redirect_uri: 'https://your-app.com/callback',
    scope: 'openid',
    prompt: 'consent'
  });

  res.redirect(`https://auth.loke.global/authorize?${params}`);
});

app.get('/callback', async (req, res) => {
  const { code } = req.query;

  const params = new URLSearchParams({
    grant_type: 'authorization_code',
    code,
    redirect_uri: 'https://your-app.com/callback'
  });

  const response = await fetch('https://auth.loke.global/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': 'Basic ' + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`)
    },
    body: params
  });

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

  // Use access_token to:
  // - Let user configure org/location mappings
  // - Set up webhooks
  // - Configure other integration settings
});

Client Credentials

async function getClientToken() {
  const params = new URLSearchParams({
    grant_type: 'client_credentials'
  });

  const response = await fetch('https://auth.loke.global/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': 'Basic ' + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`)
    },
    body: params
  });

  const { access_token } = await response.json();
  return access_token;
}

Integration Pattern

The typical integration follows this pattern:

  1. Initial Setup & Configuration

    • Use Authorization Code flow to authenticate users
    • Let users match their LOKE organizations/locations with your system
    • Configure integration settings and webhooks
    • Store the organization/location mappings for future reference

  2. Ongoing Operations

    • Use Client Credentials flow for all background tasks
    • Handle webhook events
    • Sync data between systems
    • Process automated tasks

In this article