Authentication

All requests to the Publisher API must be authenticated using an API token passed as a Bearer token in the Authorization header:

Authorization: Bearer <your-api-token>

API Tokens

API tokens are managed programmatically through the Publisher API itself. Each token has an access level that determines what operations it can perform.

Access Levels

Level	Permissions
read	Query and list operations
write	All read operations plus mutations (create, update, delete)

As a general rule, endpoints that retrieve or list data require read access, while endpoints that create, modify, or delete resources require write access.

Creating a Token

curl -X POST https://<your-instance-url>/publisher.v1/api-token/create \
  -H "Authorization: Bearer <existing-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "access": "write",
    "description": "Production integration",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Response:

{
  "id": "atok_abc123",
  "access": "write",
  "description": "Production integration",
  "token": "sk_live_a1b2c3d4...",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2025-12-31T23:59:59Z"
}

The token field is the secret value used for authentication. It is only returned once at creation time - store it securely. If you lose it, you will need to revoke the token and create a new one.

Token Expiry

The expires_at field is optional. If omitted, the token does not expire and remains valid until explicitly revoked. When a token expires, all subsequent requests using it receive a 401 response.

Listing Tokens

List all tokens to audit active credentials. The secret value is never returned in list responses.

curl -X POST https://<your-instance-url>/publisher.v1/api-token/list \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Revoking a Token

Revoke a token immediately by its ID. Once revoked, it cannot be reactivated.

curl -X POST https://<your-instance-url>/publisher.v1/api-token/revoke \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": "atok_abc123"}'

Best Practices

• Use separate tokens per service. If multiple services integrate with Publisher, issue each its own token. This simplifies auditing and allows you to revoke access to a single service without affecting others.
• Use the minimum access level required. Services that only read data should use read tokens.
• Rotate tokens periodically. Create a new token, update your service configuration, then revoke the old one.
• Set expiry for temporary access. If issuing tokens for time-limited integrations or contractors, set an appropriate expires_at.

Authentication Errors

If your request is missing a token, uses an invalid token, or the token has been revoked/expired:

{
  "error": {
    "code": "authentication_error",
    "message": "Invalid or missing API token",
    "data": {},
    "trace_id": "abc123"
  }
}

If your token is valid but lacks the required access level for the operation:

{
  "error": {
    "code": "authorization_error",
    "message": "Insufficient permissions",
    "data": {},
    "trace_id": "abc123"
  }
}