Skip to main content
Emerge uses two authentication mechanisms:
  1. API Token - Bearer token for API calls
  2. HMAC Signature - Signed URLs for the consent flow

​
API Token

Use your API token for server-to-server API calls. Include it in the Authorization header: 
curl -X GET 'https://link.emergedata.ai/consent/status/psub_c3d4e5f6789012345678901234abcdef' \
  -H 'Authorization: Bearer your_api_token'
Never expose your API token in client-side code. All API calls should be made from your backend.

​
HMAC Signing

Consent flow URLs are signed with HMAC-SHA256 to prevent tampering. The signature validates that:
  • The URL parameters haven’t been modified
  • The request originated from your application
  • The link hasn’t expired (30-day validity)

​
Signature algorithm

  1. Collect all URL parameters (except signature)
  2. Sort parameters alphabetically by key
  3. Join as key=value&key=value (raw values, not URL-encoded)
  4. Generate HMAC-SHA256 using your signing secret
  5. Append signature as hex string

​
Parameters to sign

ParameterRequiredDescription
client_idYesYour client identifier
redirect_uriYesCallback URL
stateYesCSRF protection token
timestampYesISO 8601 timestamp (e.g., 2024-01-15T10:30:00.000Z)
uidNoYour user identifier
flow_configNoNamed configuration for custom branding

​
Example signature generation

import crypto from 'crypto';

function signParams(params: Record<string, string>, signingSecret: string): string {
  // Sort parameters alphabetically
  const sortedKeys = Object.keys(params).sort();

  // Join as raw key=value pairs (NOT URL-encoded)
  const signatureBase = sortedKeys
    .map(key => `${key}=${params[key]}`)
    .join('&');

  // Generate HMAC-SHA256
  return crypto
    .createHmac('sha256', signingSecret)
    .update(signatureBase)
    .digest('hex');
}

// Usage
const params = {
  client_id: 'your_client_id',
  redirect_uri: 'https://yourapp.com/callback',
  state: 'random_state_value',
  timestamp: new Date().toISOString(),
  uid: 'psub_c3d4e5f6789012345678901234abcdef'
};

const signature = signParams(params, 'your_signing_secret');
The signature base uses raw parameter values, not URL-encoded values. URL encoding is only applied when constructing the final URL.

​
Credential management

​
Obtaining credentials

  1. Sign in to The Control Room
  2. Navigate to Settings → API Keys
  3. Generate or view your credentials
You’ll receive:
  • Client ID - Public identifier for your application
  • Signing Secret - Private key for HMAC signatures (keep secure)
  • API Token - Bearer token for API calls

​
Rotating credentials

To rotate your credentials:
  1. Go to Settings → API Keys in the Control Room
  2. Click Regenerate Keys
  3. A one-time retrieval link is emailed to the admin
  4. The link expires after 60 minutes
After regeneration, existing signed links remain valid for their 30-day period. Only new links need the new secret.

​
Security best practices

Use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault). Never commit secrets to version control.
Always verify the state parameter in callbacks matches what you sent. This prevents CSRF attacks.
Only HTTPS redirect URIs are allowed in production. This ensures the callback is encrypted.
API tokens don’t expire, but rotate them periodically as a security practice.