Authentication

Bearer API key authentication

The Pinned Events API authenticates Public API calls with API keys. The recommended public contract is Authorization: Bearer YOUR_API_KEY. Server-side integrations may also use x-api-key: YOUR_API_KEY where supported. Send exactly one authentication header.

curl https://pinned.events/api/public/v1/channels \
  -H "Authorization: Bearer YOUR_API_KEY"

Where to create API keys

Create API keys from the Developer Portal API key management page. Key management requires a signed-in user who has completed account setup.

One-time secret behavior

The full API key secret is shown only once when the key is created. List and read endpoints never return the full secret, and the stored key material is hashed.

Server-side storage

• Store API keys in environment variables or a secrets manager.
• Do not expose API keys in frontend JavaScript, public mobile clients, screenshots, logs, or repositories.
• Use one key per integration so revocation does not affect unrelated systems.
• Rotate keys if a key may have been exposed.

Key rotation and revocation

To rotate a key, create a replacement key, deploy the new secret, verify traffic, then revoke the old key. Revoked keys cannot authenticate Public API requests and remain visible only as revocation metadata.

401 Unauthorized examples

A 401 response means the API key is missing, malformed, revoked, disabled, expired, or otherwise invalid.

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid, revoked, disabled, or expired."
  }
}