API Documentation

The Golden Record API provides a centralized, authoritative source for managing organizations, users, roles, and permissions. It is designed for enterprise use cases where multiple applications need consistent access to organizational data.

Key Capabilities

• Organization Management - CRUD operations for organizations with verified/staging status
• User Management - User accounts with SSO integration via WorkOS
• Role-Based Access Control - Flexible roles and permissions system
• Organization Memberships - Connect users to organizations with specific roles
• Secure API Keys - Scoped keys with rotation, expiration, and IP allowlisting
• Real-time Sync - WorkOS User Management integration for SSO users
• Fast Search - Typesense-powered autocomplete for organizations
• Usage Analytics - Track API usage patterns and performance

Base URL

https://your-domain.com/api/v1

API Versioning

The API uses URL path versioning (e.g., /api/v1/). All endpoints are prefixed with the version number. When breaking changes are introduced, a new version will be released while maintaining backwards compatibility for existing versions.

All API requests require authentication using a Bearer token. Include your API key in the Authorization header:

Authorization: Bearer gr_live_your_api_key_here

API Key Types

Obtaining API Keys

1. Log in to the Admin Dashboard with a @gloo.us email
2. Navigate to API Keys in the sidebar
3. Click Create API Key
4. Select the required scopes and optional restrictions
5. Copy and securely store the key - it will only be shown once

The API uses cursor-based pagination for list endpoints, which is more efficient and reliable than offset-based pagination for large datasets.

How It Works

1. Make initial request with desired limit
2. Check meta.hasMore to see if more pages exist
3. Use meta.nextCursor value in next request as cursor parameter
4. Repeat until hasMore is false

Example: Fetching All Organizations

GET /api/v1/organizations?limit=50

Pagination Parameters

Organizations are the primary entities in the Golden Record. They can be verified (visible in public API results) or staging (hidden by default, useful for testing or pending approval).

Organization Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",  // UUID
  "name": "Acme Corporation",                     // Display name
  "slug": "acme-corp",                           // URL-friendly identifier
  "domain": "acme.com",                          // Primary domain (optional)
  "logoUrl": "https://example.com/logo.png",     // Logo URL (optional)
  "workosOrgId": "org_01ABC123",                 // WorkOS organization ID (if synced)
  "isVerified": true,                            // Verified = public, false = staging
  "isActive": true,                              // Soft-delete flag
  "metadata": { "industry": "technology" },      // Custom data (optional)
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Endpoints

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corporation",
      "slug": "acme-corp",
      "domain": "acme.com",
      "logoUrl": "https://example.com/logo.png",
      "workosOrgId": "org_01ABC123",
      "isVerified": true,
      "isActive": true,
      "metadata": { "industry": "technology" },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "limit": 20,
    "total": 150,
    "hasMore": true,
    "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiIsImlkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIn0"
  },
  "requestId": "req_abc123def456"
}

{
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "domain": "acme.com",
  "metadata": {
    "industry": "technology",
    "size": "enterprise"
  }
}

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "domain": "acme.com",
    "logoUrl": null,
    "workosOrgId": null,
    "isVerified": false,
    "isActive": true,
    "metadata": { "industry": "technology", "size": "enterprise" },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "requestId": "req_abc123def456"
}

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "isVerified": true,
    "message": "Organization verified successfully"
  },
  "requestId": "req_abc123def456"
}

Users represent individual accounts in the system. They can be synced from WorkOS (SSO users) or created directly via the API.

User Object

{
  "id": "user_01ABC123",                         // UUID
  "email": "john.doe@acme.com",                  // Email address (unique)
  "firstName": "John",                           // First name (optional)
  "lastName": "Doe",                             // Last name (optional)
  "avatarUrl": "https://example.com/avatar.jpg", // Avatar URL (optional)
  "workosUserId": "user_01WORKOS123",           // WorkOS user ID (if synced via SSO)
  "isActive": true,                              // Active status
  "metadata": { "department": "Engineering" },   // Custom data (optional)
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Endpoints

{
  "success": true,
  "data": [
    {
      "id": "user_01ABC123",
      "email": "john.doe@acme.com",
      "firstName": "John",
      "lastName": "Doe",
      "avatarUrl": "https://example.com/avatar.jpg",
      "workosUserId": "user_01WORKOS123",
      "isActive": true,
      "metadata": { "department": "Engineering" },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "limit": 20,
    "total": 50,
    "hasMore": false,
    "nextCursor": null
  },
  "requestId": "req_abc123def456"
}

Memberships define the relationship between users and organizations, including their assigned role.

Endpoints

{
  "success": true,
  "data": [
    {
      "id": "mem_01ABC123",
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user_01ABC123",
      "roleId": "role_01ABC123",
      "isOwner": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "user": {
        "id": "user_01ABC123",
        "email": "john.doe@acme.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "organization": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Acme Corporation",
        "slug": "acme-corp"
      },
      "role": {
        "id": "role_01ABC123",
        "name": "Admin",
        "slug": "admin"
      }
    }
  ],
  "meta": { "limit": 20, "total": 5, "hasMore": false },
  "requestId": "req_abc123def456"
}

The RBAC system provides flexible permission management. Roles contain sets of permissions that define what actions users can perform.

Roles Endpoint

{
  "success": true,
  "data": [
    {
      "id": "role_01ABC123",
      "name": "Admin",
      "slug": "admin",
      "description": "Full administrative access",
      "isSystem": true,
      "permissions": [
        { "id": "perm_01", "name": "Read Organizations", "slug": "organizations:read", "resource": "organizations", "action": "read" },
        { "id": "perm_02", "name": "Create Organizations", "slug": "organizations:create", "resource": "organizations", "action": "create" }
      ],
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "role_02ABC123",
      "name": "Member",
      "slug": "member",
      "description": "Basic member access",
      "isSystem": true,
      "permissions": [
        { "id": "perm_01", "name": "Read Organizations", "slug": "organizations:read", "resource": "organizations", "action": "read" }
      ],
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 2 },
  "requestId": "req_abc123def456"
}

Permissions Endpoint

{
  "success": true,
  "data": [
    { "id": "perm_01", "name": "Read Organizations", "slug": "organizations:read", "resource": "organizations", "action": "read" },
    { "id": "perm_02", "name": "Create Organizations", "slug": "organizations:create", "resource": "organizations", "action": "create" },
    { "id": "perm_03", "name": "Update Organizations", "slug": "organizations:update", "resource": "organizations", "action": "update" },
    { "id": "perm_04", "name": "Delete Organizations", "slug": "organizations:delete", "resource": "organizations", "action": "delete" },
    { "id": "perm_05", "name": "Read Users", "slug": "users:read", "resource": "users", "action": "read" },
    { "id": "perm_06", "name": "Create Users", "slug": "users:create", "resource": "users", "action": "create" },
    { "id": "perm_07", "name": "Update Users", "slug": "users:update", "resource": "users", "action": "update" },
    { "id": "perm_08", "name": "Delete Users", "slug": "users:delete", "resource": "users", "action": "delete" }
  ],
  "meta": { "total": 8 },
  "requestId": "req_abc123def456"
}

API keys provide secure, scoped access to the Golden Record API. Keys can be organization-scoped, IP-restricted, and time-limited.

Endpoints

{
  "success": true,
  "data": [
    {
      "id": "key_01ABC123",
      "name": "Production API Key",
      "keyPrefix": "gr_live_abc123",
      "organizationId": null,
      "scopes": ["organizations:read", "users:read"],
      "tier": "pro",
      "allowedIps": ["192.168.1.0/24", "10.0.0.1"],
      "expiresAt": "2025-01-15T10:30:00Z",
      "lastUsedAt": "2024-01-20T15:45:00Z",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 3 },
  "requestId": "req_abc123def456"
}

{
  "name": "Production API Key",
  "scopes": ["organizations:read", "organizations:create", "users:read"],
  "tier": "pro",
  "allowedIps": ["192.168.1.0/24", "10.0.0.1"],
  "expiresAt": "2025-12-31T23:59:59Z"
}

{
  "success": true,
  "data": {
    "id": "key_01ABC123",
    "name": "Production API Key",
    "key": "gr_live_sk_1234567890abcdefghijklmnopqrstuvwxyz",
    "keyPrefix": "gr_live_sk_12345",
    "organizationId": null,
    "scopes": ["organizations:read", "organizations:create", "users:read"],
    "tier": "pro",
    "allowedIps": ["192.168.1.0/24", "10.0.0.1"],
    "expiresAt": "2025-12-31T23:59:59Z",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "requestId": "req_abc123def456"
}

{
  "success": true,
  "data": {
    "oldKey": {
      "id": "key_01ABC123",
      "keyPrefix": "gr_live_sk_12345",
      "expiresAt": "2024-01-22T10:30:00Z",
      "message": "Old key will expire in 7 days"
    },
    "newKey": {
      "id": "key_02DEF456",
      "key": "gr_live_sk_newkey1234567890abcdefghij",
      "keyPrefix": "gr_live_sk_newke",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  },
  "requestId": "req_abc123def456"
}

The analytics endpoint provides insights into API usage patterns, response times, and error rates.

{
  "success": true,
  "data": {
    "summary": {
      "totalRequests": 15420,
      "successfulRequests": 15100,
      "failedRequests": 320,
      "avgResponseTimeMs": 45,
      "successRate": 97.9
    },
    "byEndpoint": [
      { "endpoint": "/api/v1/organizations", "method": "GET", "count": 8500, "avgMs": 35 },
      { "endpoint": "/api/v1/users", "method": "GET", "count": 4200, "avgMs": 42 },
      { "endpoint": "/api/v1/organizations", "method": "POST", "count": 2720, "avgMs": 68 }
    ],
    "byDay": [
      { "date": "2024-01-15", "count": 2200 },
      { "date": "2024-01-16", "count": 2450 },
      { "date": "2024-01-17", "count": 2100 }
    ]
  },
  "meta": {
    "startDate": "2024-01-15T00:00:00Z",
    "endDate": "2024-01-22T00:00:00Z"
  },
  "requestId": "req_abc123def456"
}

Webhooks allow your application to receive real-time HTTP notifications when events occur in the Golden Record. You can programmatically manage webhook subscriptions using the same API key that gives you access to other resources.

Managing Webhook Subscriptions

Use the Webhooks API to create, list, update, and delete webhook subscriptions. The same API key works for both managing webhooks and accessing other Golden Record resources.

{
  "success": true,
  "data": [
    {
      "id": "wh_01ABC123",
      "name": "Production Webhook",
      "url": "https://example.com/webhooks/golden-record",
      "events": ["organization.created", "organization.updated", "user.created"],
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 1 },
  "requestId": "req_abc123def456"
}

{
  "name": "Production Webhook",
  "url": "https://example.com/webhooks/golden-record",
  "events": ["organization.created", "organization.updated", "user.created"]
}

{
  "success": true,
  "data": {
    "id": "wh_01ABC123",
    "name": "Production Webhook",
    "url": "https://example.com/webhooks/golden-record",
    "secret": "whsec_abc123def456ghijklmnopqrstuvwxyz1234567890",
    "events": ["organization.created", "organization.updated", "user.created"],
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "requestId": "req_abc123def456"
}

{
  "events": ["*"],
  "isActive": true
}

Webhook Events

Subscribe to specific events or use * to receive all events. Events are delivered in real-time as changes occur in the system.

Event Payload Examples

organization.created

{
  "event": "organization.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "domain": "acme.com",
    "isVerified": false,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

user.created

{
  "event": "user.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "user_01ABC123",
    "email": "john.doe@acme.com",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

membership.created

{
  "event": "membership.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "mem_01ABC123",
    "organizationId": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "user_01ABC123",
    "roleId": "role_01ABC123",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Retry Behavior

If your endpoint fails to respond with a 2xx status code, we automatically retry delivery with exponential backoff:

Webhook Signature Verification

All webhook payloads are signed using HMAC-SHA256. Always verify signatures to ensure requests are authentic and prevent replay attacks.

Signature Headers

Verification Algorithm

1. Extract timestamp and signature from headers
2. Reject if timestamp is older than 300 seconds (5 minutes) - prevents replay attacks
3. Construct signed payload: {timestamp}.{raw_body}
4. Compute HMAC-SHA256 of signed payload using your webhook secret
5. Compare computed signature with received signature (use constant-time comparison)

Node.js Verification Example

import crypto from 'crypto';

function verifyWebhook(rawBody: string, headers: Headers, secret: string): boolean {
  const timestamp = headers.get('X-Webhook-Timestamp');
  const signature = headers.get('X-Webhook-Signature');
  
  if (!timestamp || !signature) {
    return false;
  }
  
  // Check timestamp is within 5 minutes
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (timestampAge > 300) {
    return false; // Replay attack protection
  }
  
  // Compute expected signature
  const signedPayload = `${timestamp}.${rawBody}`;
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Python Verification Example

import hmac
import hashlib
import time

def verify_webhook(raw_body: str, headers: dict, secret: str) -> bool:
    timestamp = headers.get('X-Webhook-Timestamp')
    signature = headers.get('X-Webhook-Signature')
    
    if not timestamp or not signature:
        return False
    
    # Check timestamp is within 5 minutes
    timestamp_age = int(time.time()) - int(timestamp)
    if timestamp_age > 300:
        return False
    
    # Compute expected signature
    signed_payload = f"{timestamp}.{raw_body}"
    expected_sig = 'sha256=' + hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    # Constant-time comparison
    return hmac.compare_digest(signature, expected_sig)

Best Practices

The Golden Record integrates with WorkOS User Management to sync users who authenticate via SSO. This provides a unified view of all users across your applications.

How It Works

1. Users authenticate via WorkOS AuthKit (SSO)
2. WorkOS sends real-time webhook events for user lifecycle changes
3. Golden Record creates/updates local user records
4. User matching: checks by workosUserId first, then falls back to email

Sync Capabilities

WorkOS User Fields Synced

The Golden Record uses Typesense for blazing-fast, typo-tolerant search. Currently supports organization search with autocomplete functionality.

Search Features

• Typo tolerance - handles misspellings gracefully
• Instant autocomplete results
• Searches across name, slug, and domain fields
• Respects verified/staging organization status

Using Search

Use the search query parameter on the organizations list endpoint:

GET /api/v1/organizations?search=acme&limit=10

// Returns organizations matching "acme" with typo tolerance
// Also matches "acne", "acma", etc.