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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.