# Authentication

Source: https://staging-docs.aiand.com/authentication/

All API endpoints require authentication. ai& supports two methods:

## API Key (recommended)

Pass your API key in the `Authorization` header:

```http
Authorization: Bearer sk-your-api-key
```

API keys are scoped to an organization. Each key resolves the associated billing account automatically.

<Aside type="caution">
  API keys are shown once at creation time. Store them securely — you cannot
  retrieve the full key later.
</Aside>

### Key format

All API keys start with the `sk-` prefix.

### Key management

Create, list, update, and revoke API keys from the [console](https://console.aiand.com) or via the management API:

| Action | Endpoint |
|--------|----------|
| List keys | `GET /api/v1/keys` |
| Create key | `POST /api/v1/keys` |
| Update key | `PATCH /api/v1/keys/{key_id}` |
| Delete key | `DELETE /api/v1/keys/{key_id}` |

All key management endpoints require the `X-Org-ID` header set to your organization ID.

## JWT (session auth)

Browser-based clients authenticate via JWT tokens stored in `httpOnly` cookies. This is used by the console web app and is not recommended for programmatic API access.

- **Access token**: 15-minute TTL, set as `access_token` cookie
- **Refresh token**: 30-day TTL, set as `refresh_token` cookie

JWTs are issued via OAuth (Google/GitHub) or magic link sign-in flows.

## Organization context

API keys are bound to an organization. When authenticating with an API key, the organization is resolved automatically from the key.

When using JWT auth, pass the `X-Org-ID` header to specify which organization context to use.

## Error responses

| Status | Meaning |
|--------|---------|
| `401` | Missing or invalid credentials |
| `402` | Insufficient credits in the billing account |
| `403` | Valid credentials but insufficient permissions |

See [Error Codes](/errors/) for the full error response format.