Skip to main content

​
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

1

Log in to Dashboard

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

Access API Keys Section

Click Settings → API Keys in the sidebar
3

Create New Key

Click Create API Key button
4

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
5

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"}'

​
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

  • 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)
  • 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
  • Regularly review API key activity in the dashboard
  • Set up alerts for unusual usage patterns
  • Immediately revoke compromised keys
  • 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:
PlanRequests per hourRequests per day
Free10010,000
Starter300100,000
Professional1,200500,000
EnterpriseCustomCustom

​
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
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetISO 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