Authentication

Every request — apart from the public embed endpoints — is authenticated with an API key, sent in the x-api-key request header.

Sending your API key

Send the key in the x-api-key header on every request:

curl https://api.knips.com/feeds \
  -H "x-api-key: YOUR_API_KEY"

A request missing the header — or with an unrecognized key — is rejected with 403 Forbidden resource. A valid key without the right permission gets the same 403.

Legacy Basic authentication

Existing integrations can keep sending the key as HTTP Basic auth, with the key's access id and secret as the username and password:

curl https://api.knips.com/feeds \
  -u "YOUR_ACCESS_ID:YOUR_SECRET"

Both forms stay supported, but prefer x-api-key for new integrations. The same credentials work in the header too: send base64(YOUR_ACCESS_ID:YOUR_SECRET) as the key value.

Getting an API key

API keys are issued per workspace or per organisation. Store the key somewhere safe when it is created.

A key reaches the data of the workspace it belongs to — an organisation key reaches every workspace in the organisation.

Permissions

Every key has a set of permissions, one per resource — read-only or read-write (read-write covers read-only too). Each endpoint's reference page shows the permission it needs. Call something your key isn't allowed to and you get the same 403 Forbidden resource as with an invalid key.

Verifying your key

Check that a key works — and what it can do — with the authorization endpoint. It returns the workspace or organisation the key is scoped to, plus its permissions:

curl https://api.knips.com/authorization \
  -H "x-api-key: YOUR_API_KEY"

Keep your key safe

• Store the key in a secret manager or environment variable, never in source control.
• Rotate a key immediately if you suspect it has leaked.
• Use a separate key per integration so you can revoke one without breaking the others.