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.
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:

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:

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:

{
  "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.