---
title: "Authentication - Documentation"
description: "API key management, token scopes, and security best practices for API authentication."
canonical: "https://www.aifordatabase.com/docs/authentication/"
---

# Authentication

intermediate 5 min read

## API Authentication

AI for Database uses API keys for server-to-server and agent authentication. Authentication does not bypass credit checks; AI usage is deducted from the same non-expiring individual user balance.

### API Keys

Generate API keys in **Settings > API Keys** (or programmatically via `POST /api/v1/keys`). Each key is a long-lived secret that authenticates requests on behalf of your organization, with the role of the user who created it.

**Creating a key:**

1.  1Click **New API Key**
2.  2Give it a descriptive name (e.g., "Production Backend", "CI Pipeline")
3.  3Select the scopes it needs (see below)
4.  4Optionally set an expiration date
5.  5Copy the key immediately -- it is only shown once

**Using the key:**

All keys start with the `afd_` prefix and are passed as a Bearer token:

```bash
curl https://app.aifordatabase.com/api/v1/connections \
  -H "Authorization: Bearer afd_abc123..."
```

### Key Scopes

Each key carries a set of scopes; endpoints require the scope of their area. A key with the `*` scope has full access.

| Scope | Grants access to |
| --- | --- |
| `query` | Direct SQL execution, query submission, approval status, saved query runs |
| `chat` | Natural-language chat endpoints |
| `connections` | Sanitized database connection metadata, schemas, and annotations |
| `dashboards` | Dashboards and widgets |
| `workflows` | Workflows and workflow runs |
| `workflow_credentials` | Encrypted outbound workflow credentials (admin role also required) |
| `usage` | Usage records and budget info |
| `webhooks` | Webhook endpoints and deliveries |
| `admin` | Key management and other admin operations |

Requests missing a required scope return HTTP 403 with code `FORBIDDEN`. Invalid or expired keys return HTTP 401 with code `UNAUTHORIZED`.

Notethat some operations also require an **admin role** in the organization regardless of key scopes. Workflow credential creation, rotation, listing, and deletion require both the `workflow_credentials` scope and the admin role. Give an automation agent `connections`, `query`, `workflows`, and `workflow_credentials` when it must inspect a source, validate raw query results, and configure authenticated webhook alerts end to end.

API keys authenticate callers to the AI for Database public API. They are separate from encrypted workflow credentials, which authenticate an outbound webhook action to its destination and are never accepted inline in a workflow definition.

### Security Best Practices

*   Store API keys in environment variables, never in code.
*   Use the narrowest scopes necessary.
*   Rotate keys periodically and revoke unused keys (`DELETE /api/v1/keys/:id`).
*   Create separate keys per integration so each can be revoked independently.

Source: https://www.aifordatabase.com/docs/authentication/