En Garde Developer Portal | API Documentation & Integration Guides

Developer Portal

← Back to Docs

OAuth 2.0 + PKCE Authorization Guide

Implement secure authorization for your EnGarde integration

Overview

EnGarde uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for authorization. This ensures secure access to customer data while preventing authorization code interception attacks.

Prerequisites

1. Register your application to get OAuth client credentials

2. Configure redirect URIs in your application settings

3. Select the required OAuth scopes for your use case

Authorization Flow

Step 1: Generate PKCE Parameters

Generate a code verifier and code challenge for PKCE:

// Generate code verifier (random 43-128 character string)
const codeVerifier = generateRandomString(128);

// Generate code challenge (SHA-256 hash, base64url encoded)
const codeChallenge = base64url(sha256(codeVerifier));

Step 2: Redirect to Authorization URL

Direct users to the EnGarde authorization endpoint:

const authUrl = new URL('https://api.engardehq.com/v1/oauth/authorize');
authUrl.searchParams.append('client_id', YOUR_CLIENT_ID);
authUrl.searchParams.append('redirect_uri', YOUR_REDIRECT_URI);
authUrl.searchParams.append('response_type', 'code');
authUrl.searchParams.append('scope', 'conversational_analytics metrics');
authUrl.searchParams.append('code_challenge', codeChallenge);
authUrl.searchParams.append('code_challenge_method', 'S256');
authUrl.searchParams.append('state', randomStateValue);

// Redirect user to authUrl
window.location.href = authUrl.toString();

Step 3: Handle Authorization Callback

EnGarde redirects back to your redirect URI with an authorization code:

// Your callback endpoint receives:
// https://yourapp.com/callback?code=AUTH_CODE&state=STATE_VALUE

const urlParams = new URLSearchParams(window.location.search);
const authCode = urlParams.get('code');
const state = urlParams.get('state');

// Verify state matches what you sent

Step 4: Exchange Code for Access Token

Exchange the authorization code for an access token using the code verifier:

const response = await fetch('https://api.engardehq.com/v1/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    client_id: YOUR_CLIENT_ID,
    client_secret: YOUR_CLIENT_SECRET,
    code: authCode,
    redirect_uri: YOUR_REDIRECT_URI,
    code_verifier: codeVerifier, // From Step 1
  }),
});

const data = await response.json();
const accessToken = data.access_token;
const refreshToken = data.refresh_token;
const expiresIn = data.expires_in; // Seconds until expiration

Step 5: Use Access Token

Include the access token in API requests:

const response = await fetch('https://api.engardehq.com/v1/analytics/conversations', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
  },
});

const analytics = await response.json();

Step 6: Refresh Access Token

When the access token expires, use the refresh token to get a new one:

const response = await fetch('https://api.engardehq.com/v1/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'refresh_token',
    client_id: YOUR_CLIENT_ID,
    client_secret: YOUR_CLIENT_SECRET,
    refresh_token: refreshToken,
  }),
});

const data = await response.json();
const newAccessToken = data.access_token;

Security Best Practices

• Always use HTTPS for redirect URIs in production

• Store client secrets securely (never expose in client-side code)

• Validate the state parameter to prevent CSRF attacks

• Store access and refresh tokens securely (encrypted storage recommended)

• Implement token rotation and revocation

• Request only the scopes your application needs

Available Scopes

Scope	Description
conversational_analytics	Read conversational analytics and chat logs
user_data	Read user profiles and basic information
metrics	Access usage metrics and analytics dashboards
write_data	Create and modify user data (requires approval)

Need Help?

If you have questions about implementing OAuth, contact our developer support team.