> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication with Bearer Keys

> Authenticate gu1 API requests using bearer API keys, including how to issue keys from the dashboard, scope permissions, and rotate credentials.

## 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](#api-key-format) below).

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

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

## Getting Your API Key

<Steps>
  <Step title="Log in to Dashboard">
    Navigate to [app.gu1.ai](https://app.gu1.ai) and log in to your account
  </Step>

  <Step title="Access API Keys Section">
    Click **Settings** → **API Keys** in the sidebar
  </Step>

  <Step title="Create New Key">
    Click **Create API Key** button
  </Step>

  <Step title="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
  </Step>

  <Step title="Copy and Store">
    Copy the generated key immediately - it will only be shown once!
  </Step>
</Steps>

## Using Your API Key

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

```bash theme={null}
curl http://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_prod_YOUR_KEY_HERE"
```

### Example with Different Methods

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```javascript JavaScript / Node.js theme={null}
  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'
    })
  });
  ```

  ```python Python theme={null}
  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
  )
  ```
</CodeGroup>

## 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.

<Note>
  Follow the principle of least privilege — prefer explicit `resource:action` grants over broad access.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion icon="lock" title="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`)
  </Accordion>

  <Accordion icon="rotate" title="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
  </Accordion>

  <Accordion icon="shield-halved" title="Monitor Usage">
    * Regularly review API key activity in the dashboard
    * Set up alerts for unusual usage patterns
    * Immediately revoke compromised keys
  </Accordion>

  <Accordion icon="code-branch" title="Environment Separation">
    * Use test keys for development and staging
    * Use live keys only in production
    * Never use live keys on developer machines
  </Accordion>
</AccordionGroup>

## Error Responses

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

### Missing API Key

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No API key provided"
  }
}
```

**HTTP Status:** `401 Unauthorized`

### Invalid API Key

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key provided"
  }
}
```

**HTTP Status:** `401 Unauthorized`

### Expired API Key

```json theme={null}
{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "API key has expired"
  }
}
```

**HTTP Status:** `401 Unauthorized`

### Insufficient Permissions

```json theme={null}
{
  "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:

```http theme={null}
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:

```json theme={null}
{
  "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:**

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-01-15T10:00:00Z
Retry-After: 3600
```

<Tip>
  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.
</Tip>

## Testing Your API Key

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

```bash theme={null}
curl http://api.gu1.ai/auth/test \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response:**

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Create Your First Entity" icon="building" href="/en/api-reference/entities/create">
    Start using the API to create entities
  </Card>

  <Card title="Define Custom Schemas" icon="table" href="/en/api-reference/data-ingestion/custom-schemas">
    Set up data mapping for your use case
  </Card>

  <Card title="Webhooks" icon="webhook" href="/en/webhooks/overview">
    Receive real-time notifications
  </Card>

  <Card title="KYC complete flow" icon="book" href="/en/use-cases/kyc/complete-flow">
    End-to-end KYC integration guide
  </Card>
</CardGroup>