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. 
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 on 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”)
  • Set permissions (read, write, admin)
  • 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 sk_live_abc123..."

​
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 Types

gu1 offers different types of API keys for different environments:

Live Keys

Start with sk_live_Used for production environments. All operations are real and affect your live data.

Test Keys

Start with sk_test_Used for development and testing. Operations don’t affect your production data.

​
Permissions

API keys can have different permission levels:
PermissionDescriptionUse Case
ReadView entities, rules, and dataAnalytics dashboards, reporting
WriteCreate and update entitiesData ingestion, API integrations
AdminFull access including key managementInfrastructure automation
Follow the principle of least privilege - only grant the minimum permissions needed for each integration.

​
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: 
{
  "authenticated": true,
  "organization_id": "org_abc123",
  "permissions": ["read", "write"],
  "key_type": "live"
}

​
Next Steps

Create Your First Entity

Start using the API to create entities

Define Custom Schemas

Set up data mapping for your use case

Setup Webhooks

Receive real-time notifications

Integration Guide

Follow our complete integration guide