API Authentication with Bearer Keys

Overview

gu1 uses API keys to authenticate requests. All API requests must include your API key in the Authorization header using the Bearer scheme. Keys are issued in the format gk_<environment>_... (see API key format below).

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure! Never commit them to version control or share them publicly.

Getting Your API Key

Navigate to app.gu1.ai and log in to your account

Access API Keys Section

Click Settings → API Keys in the sidebar

Create New Key

Click Create API Key button

Configure Key

Give your key a descriptive name (e.g., “Production API”, “Development”)
Open Manage permissions and select granular permissions (resource:action pairs) aligned with your workspace RBAC. Grant only what the integration needs.
Optionally set an expiration date

Copy and Store

Copy the generated key immediately - it will only be shown once!

Using Your API Key

Include your API key in the Authorization header of every request:

curl http://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_prod_YOUR_KEY_HERE"

Example with Different Methods

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "company", "name": "Acme Corp"}'

const response = await fetch('http://api.gu1.ai/entities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'company',
    name: 'Acme Corp'
  })
});

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}

data = {
    'type': 'company',
    'name': 'Acme Corp'
}

response = requests.post(
    'http://api.gu1.ai/entities',
    headers=headers,
    json=data
)

API Key Format

API keys are opaque strings with the prefix gk_, followed by an environment segment and a random suffix (for example gk_prod_...). The segment reflects the environment you chose when creating the key (for example production vs sandbox). Use production keys only with production organizations and data.

Permissions

Permissions are granular: in the dashboard you assign allowed resources and actions (the same resource:action model as workspace RBAC). Each integration should receive the smallest set of permissions required for its endpoints.

Follow the principle of least privilege — prefer explicit resource:action grants over broad access.

Best Practices

Secure Storage

Store API keys in environment variables or secret management systems
Never hardcode keys in your source code
Never commit keys to version control (use .env files and .gitignore)

Key Rotation

Rotate API keys regularly (every 90 days recommended)
Create new keys before revoking old ones to avoid downtime
Update all systems that use the old key

Monitor Usage

Regularly review API key activity in the dashboard
Set up alerts for unusual usage patterns
Immediately revoke compromised keys

Environment Separation

Use test keys for development and staging
Use live keys only in production
Never use live keys on developer machines

Error Responses

If authentication fails, you’ll receive one of these error responses:

Missing API Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No API key provided"
  }
}

HTTP Status: 401 Unauthorized

Invalid API Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key provided"
  }
}

HTTP Status: 401 Unauthorized

Expired API Key

{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "API key has expired"
  }
}

HTTP Status: 401 Unauthorized

Insufficient Permissions

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have permission to perform this action"
  }
}

HTTP Status: 403 Forbidden

Rate Limiting

API keys are subject to rate limits based on your plan:

Plan	Requests per hour	Requests per day
Free	100	10,000
Starter	300	100,000
Professional	1,200	500,000
Enterprise	Custom	Custom

Rate Limit Headers

All API responses include rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 2025-01-15T10:00:00Z

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	ISO 8601 timestamp when the rate limit resets

Rate Limit Exceeded Response

When you exceed rate limits, you’ll receive:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "You have exceeded your API rate limit. Please wait before making more requests.",
  "retryAfter": 3600,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2025-01-15T10:00:00Z"
}

HTTP Status: 429 Too Many Requests Response Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-01-15T10:00:00Z
Retry-After: 3600

Monitor the rate limit headers in your responses to implement proactive rate limiting in your application. The Retry-After header indicates how many seconds you should wait before retrying.

Testing Your API Key

Use this simple test to verify your API key is working:

curl http://api.gu1.ai/auth/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

{
  "valid": true,
  "apiKey": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production API",
    "environment": "prod",
    "organizationId": "550e8400-e29b-41d4-a716-446655440001",
    "scopes": [],
    "rateLimit": 1000,
    "rateLimitRemaining": 999,
    "expiresAt": null,
    "lastUsedAt": "2026-01-10T12:00:00.000Z"
  }
}

Next Steps

Create Your First Entity

Start using the API to create entities

Define Custom Schemas

Set up data mapping for your use case

Webhooks

Receive real-time notifications

KYC complete flow

End-to-end KYC integration guide

​Overview

​Getting Your API Key

​Using Your API Key

​Example with Different Methods

​API Key Format

​Permissions

​Best Practices

​Error Responses

​Missing API Key

​Invalid API Key

​Expired API Key

​Insufficient Permissions

​Rate Limiting

​Rate Limit Headers

​Rate Limit Exceeded Response

​Testing Your API Key

​Next Steps

Create Your First Entity

Define Custom Schemas

Webhooks

KYC complete flow

Overview

Getting Your API Key

Using Your API Key

Example with Different Methods

API Key Format

Permissions

Best Practices

Error Responses

Missing API Key

Invalid API Key

Expired API Key

Insufficient Permissions

Rate Limiting

Rate Limit Headers

Rate Limit Exceeded Response

Testing Your API Key

Next Steps