---
title: "Authentication"
description: "Authenticate with the Octopost API using API keys"
---

# Authentication

All API requests must be authenticated using an API key passed as a Bearer token.

## Generating API Keys

1. Log in to the [Octopost Dashboard](https://octopost.ink/dashboard/settings).
2. Navigate to **Settings > API Keys**.
3. Click **Create API Key**.
4. Give the key a descriptive name (e.g., "Production Server", "CI/CD Pipeline").
5. Select the permissions for the key.
6. Copy the key immediately -- it will only be displayed once.

## Using Your API Key

Include the key in the `Authorization` header on every request:

```bash
curl https://api.octopost.ink/v1/posts \
  -H "Authorization: Bearer oct_live_abc123def456"
```

API keys use the prefix `oct_live_` for production keys and `oct_test_` for test keys. Test keys can only access sandbox data and will never publish to real social media accounts.

## Key Permissions

When creating an API key, you can scope it to specific permissions:

| Permission | Description |
|-----------|-------------|
| `posts:read` | List and retrieve posts |
| `posts:write` | Create, update, delete, and publish posts |
| `accounts:read` | List and retrieve connected accounts |
| `accounts:write` | Connect and disconnect social accounts |
| `presets:read` | List and retrieve publishing presets |
| `presets:write` | Create, update, and delete presets |
| `webhooks:read` | List and retrieve webhooks |
| `webhooks:write` | Create, update, and delete webhooks |

A key with no explicit permissions has full access. For security, prefer scoping keys to only the permissions they need.

## Key Rotation

You can have multiple active API keys at the same time. To rotate a key:

1. Create a new API key with the same permissions.
2. Update your application to use the new key.
3. Verify the new key is working in production.
4. Revoke the old key from the dashboard.

Revoking a key takes effect immediately. Any in-flight requests using the revoked key will fail with a `401 Unauthorized` response.

## Security Best Practices

- **Never commit API keys to version control.** Use environment variables or a secrets manager.
- **Use the narrowest permissions possible.** A key that only needs to create posts should not have `accounts:write`.
- **Use test keys for development.** Test keys (`oct_test_`) cannot publish to real accounts.
- **Rotate keys periodically.** Rotate production keys at least every 90 days.
- **Revoke compromised keys immediately.** If a key is exposed, revoke it from the dashboard without delay.
- **Use separate keys per environment.** Maintain distinct keys for development, staging, and production.

## Error Responses

If authentication fails, the API returns a `401 Unauthorized` response:

```json
{
  "error": "Invalid or expired API key",
  "code": "unauthorized"
}
```

Common causes:

- The API key is missing from the request.
- The `Authorization` header is malformed (must be `Bearer <key>`).
- The API key has been revoked.
- A test key is being used against a production endpoint that requires a live key.