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

# Authentication API

> Register, login, and manage API keys programmatically

## Overview

AudioPod AI supports two authentication methods:

* **API Key**: Use `X-API-Key` header (recommended for servers)
* **JWT Token**: Use `Authorization: Bearer {token}` header (for sessions)

***

## Registration

### Step 1: Initiate Registration

```bash theme={null}
curl -X POST "https://api.audiopod.ai/api/v1/auth/initiate-registration" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "SecurePass123",
    "full_name": "Developer Name"
  }'
```

**Response:**

```json theme={null}
{
  "message": "Verification code sent to your email. Please check your inbox."
}
```

### Step 2: Verify Email

```bash theme={null}
curl -X POST "https://api.audiopod.ai/api/v1/auth/verify-registration" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "verification_code": "123456"
  }'
```

**Response:**

```json theme={null}
{
  "user": {
    "id": "uuid",
    "email": "dev@example.com",
    "full_name": "Developer Name",
    "is_verified": true
  },
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}
```

***

## Login

```bash theme={null}
curl -X POST "https://api.audiopod.ai/api/v1/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=dev@example.com&password=SecurePass123"
```

**Response:** Same as verify-registration.

***

## API Keys

### Create API Key

Use JWT token from login/registration:

```bash theme={null}
curl -X POST "https://api.audiopod.ai/api/v1/auth/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-key",
    "scopes": ["*"],
    "expires_in_days": null
  }'
```

**Response:**

```json theme={null}
{
  "id": "key-uuid",
  "name": "production-key",
  "api_key": "ap_xxxxxxxxxxxxxxxx",
  "scopes": ["*"],
  "created_at": "2025-01-01T00:00:00Z",
  "expires_at": null
}
```

<Warning>The `api_key` is only shown once. Save it immediately!</Warning>

### List API Keys

```bash theme={null}
curl -X GET "https://api.audiopod.ai/api/v1/auth/api-keys" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"
```

### Revoke API Key

```bash theme={null}
curl -X DELETE "https://api.audiopod.ai/api/v1/auth/api-keys/{key_id}" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"
```

***

## Password Reset

### Request Reset

```bash theme={null}
curl -X POST "https://api.audiopod.ai/api/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'
```

### Confirm Reset

```bash theme={null}
curl -X POST "https://api.audiopod.ai/api/v1/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset_token_from_email",
    "new_password": "NewSecurePass123"
  }'
```

***

## Token Refresh

```bash theme={null}
curl -X POST "https://api.audiopod.ai/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'
```

***

## Get Current User

```bash theme={null}
curl -X GET "https://api.audiopod.ai/api/v1/auth/me" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"
```

**Response:**

```json theme={null}
{
  "id": "uuid",
  "email": "dev@example.com",
  "full_name": "Developer Name",
  "is_verified": true,
  "created_at": "2025-01-01T00:00:00Z"
}
```

***

## Errors

| Code  | Error                       | Description             |
| ----- | --------------------------- | ----------------------- |
| `401` | `invalid_credentials`       | Wrong email or password |
| `401` | `token_expired`             | Access token expired    |
| `400` | `email_already_registered`  | Email already in use    |
| `400` | `invalid_verification_code` | Wrong or expired code   |
| `429` | `rate_limit_exceeded`       | Too many requests       |

***

## Quick Reference

| Endpoint                      | Method | Auth     | Description        |
| ----------------------------- | ------ | -------- | ------------------ |
| `/auth/initiate-registration` | POST   | None     | Start registration |
| `/auth/verify-registration`   | POST   | None     | Verify email       |
| `/auth/token`                 | POST   | None     | Login              |
| `/auth/refresh`               | POST   | None     | Refresh token      |
| `/auth/forgot-password`       | POST   | None     | Request reset      |
| `/auth/reset-password`        | POST   | None     | Confirm reset      |
| `/auth/me`                    | GET    | Required | Get user info      |
| `/auth/api-keys`              | GET    | Required | List API keys      |
| `/auth/api-keys`              | POST   | Required | Create API key     |
| `/auth/api-keys/{id}`         | DELETE | Required | Revoke API key     |