# Authentication

All API requests require an API key. Keys are issued per organisation and scoped to a role.

***

## API keys

Obtain an API key from the dashboard under **Settings → API Keys → New Key**. Each key is tied to a role (`owner`, `admin`, `operator`, or `viewer`) - see [Security Model](https://docs.fervusai.com/core-concepts/security-model) for role permissions.

**Keep your API key secret.** It grants access to your organisation's wallets, balances, and policies. Do not commit it to source control or expose it in client-side code.

***

## Making authenticated requests

Pass your API key in the `Authorization` header as a Bearer token:

```bash
curl https://api.fervus.ai/v1/wallets \
  -H "Authorization: Bearer FERVUS_API_KEY"
```

All requests must be made over HTTPS. HTTP requests are rejected.

***

## SDK configuration

The SDK accepts the API key at initialisation:

```typescript
import { FervusAI } from "@fervusai/sdk";

const client = new FervusAI({
  apiKey: process.env.FERVUS_API_KEY,
});
```

```python
import fervusai

client = fervusai.Client(api_key=os.environ["FERVUS_API_KEY"])
```

Never hardcode the key. Always read it from an environment variable or secrets manager.

***

## Key rotation

Rotate a compromised or expired key in the dashboard: **Settings → API Keys → \[key name] → Rotate**. The old key is immediately invalidated. Generate a new key and update your environment before rotating.

Programmatic rotation:

```typescript
await client.apiKeys.rotate("key_abc123");
```

***

## Response on authentication failure

An invalid or missing API key returns `401 Unauthorized`:

```json
{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or missing API key.",
    "docs": "https://docs.fervus.ai/api-reference/authentication"
  }
}
```

An API key with insufficient permissions for the requested operation returns `403 Forbidden`:

```json
{
  "error": {
    "code": "insufficient_permissions",
    "message": "This API key does not have permission to create wallets.",
    "required_role": "admin",
    "docs": "https://docs.fervus.ai/api-reference/authentication"
  }
}
```

***

## Rate limits

| Tier            | Requests per second | Burst  |
| --------------- | ------------------- | ------ |
| Beta (all orgs) | 50 req/s            | 200    |
| Enterprise      | Custom              | Custom |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1746000060
```

When rate-limited, the API returns `429 Too Many Requests`. Implement exponential backoff with jitter when handling 429 responses.

***

## Base URL

```
https://api.fervus.ai/v1
```

All endpoints are versioned. The current version is `v1`. Breaking changes will introduce a new version prefix - `v1` will remain available for a deprecation window of at minimum 12 months.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fervusai.com/api-reference/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.