Authentication

Send the key as a bearer credential

Put the key in the Authorization header and nowhere else — not in a URL, a request body, a log line, or browser storage.

Authorization: Bearer $SEEKOUT_API_KEY

A missing, malformed, expired, or revoked key returns 401. A valid key without permission for that operation returns 403. The two are never interchangeable — see errors.

Test and live keys

Every key looks like so_ext_… and belongs to one environment. Test keys are for development; live keys spend your organization's credits. A deployment accepts one environment, so presenting a key from the other one fails as 401 — a test key can never bill a live account by accident.

This deployment accepts live keys only: every paid call spends your organization's real credits, and a test key is refused with 401.

GET /v1/whoami reports the key you are actually using: its workspace_id, org_root, application_id, audience, and the exact scopes it carries. It needs no permission beyond a valid key, which makes it the fastest way to check a deployment. It does not charge credits.

curl --request GET "https://developer-api.seekout.io/v1/whoami" \
  --header "Authorization: Bearer $SEEKOUT_API_KEY"

API access sets

A key is created against one or more API access sets, and those sets decide which operations it may call. Ask for the narrowest set your integration needs — a key can be replaced with a broader one later without changing your code.

GET /v1/whoami needs no extra permission. The API reference lists only the operations this API serves. A valid key without candidates.search still verifies, then returns 403 on search. Unlock needs profiles.v1:unlock.

What happens on every request

• The API reads the key from the Authorization header. A malformed or duplicated credential fails before anything else runs.
• SeekOut validates the key for workspace, environment, permissions, and revocation before the operation runs. A downstream provider never receives your key or decides its authority.
• The API enforces the operation's permission itself, and rejects any organization or account identifier sent in the request body.
• Your key is never forwarded to a downstream provider; results come back with opaque SeekOut identifiers.

Rotation and revocation

Rotate a key from API keys when you suspect exposure or on your own schedule. Rotation issues a new key alongside the old one so you can deploy before revoking; revocation takes effect on the next request.