Authentication

API keys

Every request is authenticated with an API key, sent as a header:

x-api-key: sk_scout_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
content-type: application/json

Keys are created and revoked by an administrator from your organisation's Developer page in the Scout Select dashboard. The plaintext key is shown exactly once at creation time - only a prefix and last 4 characters are stored and displayed afterwards, so save it somewhere safe immediately.

A key can optionally have:

• An expiry date (expiresAt) - after which requests using it are rejected.
• Allowed hosts (allowedHosts) - if set, the key only works when the request's Host header matches one of them (Scout Select's own domains are always implicitly allowed).
• Required headers (requiredHeaders) - additional header names that must be present (non-empty) on every request using this key, for partners who want an extra shared-secret check on top of the API key itself.

If a key is invalid, revoked, expired, or a host/header requirement isn't met, the request is treated as unauthenticated.

Scopes

Each key is issued with one or more scopes. A request fails if the operation it calls needs a scope the key doesn't have.

Webhook signing secret

If you create a key with the intent to use callbacks, a plaintextWebhookSigningSecret is also returned once at creation time. Use it to verify the X-Scout-Signature header on incoming callbacks - see certification webhooks or assessment webhooks.

Webhook domain allowlist

Independent of allowedHosts (which restricts who can use your API key), your organisation can optionally restrict which hostnames a callbackUrl webhook is allowed to target - for both certification invites and assessment assignments. This is configured on the Developer page in the dashboard by an org admin (not settable via the API itself), under "Allowed Webhook Domains".

• With no domains configured, any HTTPS callbackUrl is accepted - this is the default, matching prior behavior.
• Once you add one or more domains, only callbackUrls whose exact hostname matches an entry in the list are accepted; anything else is rejected with BAD_USER_INPUT at invite/assignment time (not at delivery time). Matching is exact hostname only - no wildcard subdomains.