Authentication

The RedPennon API authenticates each request with an environment API key — a UUID issued per environment (development, testing, production) within your organisation. There is no user session and no OAuth flow.

Obtain an API key

Environment API keys are managed in the RedPennon app:

1. Sign in at app.redpennon.dev.
2. Open your organisation, then Environments.
3. Pick the environment you want to issue requests against (for example, production).
4. Copy its API key — a UUID like 00000000-0000-0000-0000-000000000000.

Environments are scoped to individual projects — each project has its own set of environments (for example, development, staging, production), and each environment has its own API key. See Environments for the full model.

Header

Send the key in the X-API-Key request header on every call:

Host: api.redpennon.dev
Content-Type: application/json
X-API-Key: 00000000-0000-0000-0000-000000000000

HTTP treats header names as case-insensitive; clients should send X-API-Key.

Rotation

Rotate keys when an environment changes hands

Regenerate the API key from the environment settings page if a key is leaked, an integration is decommissioned, or someone with the key leaves the team. Rotation is immediate — old keys stop authenticating on the next request. Plan a brief overlap by deploying clients with the new key before regenerating.

401 behaviour

Any request with a missing, malformed, or unknown API key gets a single uniform error response:

{ "error": "Invalid or missing API key." }

Status: 401 Unauthorized. The API does not distinguish between "no header sent" and "header present but invalid" — both shape your retries the same way.

See Errors for the complete error matrix.

Organisation API tokens (rpa_)

Some endpoints authenticate with an organisation API token rather than the per-environment X-API-Key. These are bearer tokens, prefixed rpa_, scoped to a whole organisation (not a single environment), and are used by the code references ingest endpoint and the RedPennon CLI / GitHub Action.

Create one in the app under Settings → API tokens (owner or org admin). The full token is shown once at creation — store it securely (for CI, as a repository secret). Only a short prefix is retained for display; the rest is stored as a SHA-256 hash and can never be recovered.

Send it as a bearer token:

Host: api.redpennon.dev
Authorization: Bearer rpa_xxxxxxxxxxxxxxxxxxxxxxxx

A missing, malformed, unknown, or revoked token returns:

{ "error": "Invalid or missing API token." }

Status: 401 Unauthorized. Revoke a token from the same tab; revocation is immediate.

Token	Header	Scope	Used by
Environment API key	X-API-Key	One environment	Flag evaluation
Organisation API token	Authorization: Bearer rpa_…	Whole organisation	Code references ingest