Authentication
API keys: where they come from, how to send one, how to revoke one.
The API authenticates with an API key sent as a bearer token.
curl "https://api.enrichednow.com/v1/runs" \
-H "Authorization: Bearer $ENRICHEDNOW_API_KEY"API keys#
| Format | en_live_ followed by 32 or more URL-safe characters |
| Header | Authorization: Bearer <key> |
| Created | In the console, under API keys |
| Shown | Once, when the key is created |
| Stored by us | As a SHA-256 hash, with the 8 characters that follow en_live_ kept as a prefix so you can tell your keys apart |
Because we keep only a hash, a lost secret cannot be shown again. Create a new key and revoke the old one.
Each key has a name you choose, the prefix, and three times: when it was created, when it was last used, and when it was revoked (if it was).
Create a key#
In the console, open API keys, create a key with a name of your choosing, and copy the secret.
Give each program or environment its own key. Then a leaked key can be revoked without stopping everything else,
and last_used_at tells you which keys are still in use.
Revoke a key#
In the console, open API keys and revoke the key. A revoked key stops working at once; every later request with it is
answered 401 with the code unauthorized.
Which endpoints need a key#
| Endpoints | Auth |
|---|---|
GET /v1/health, GET /v1/scrapers, GET /v1/scrapers/{id} | None. The catalogue is public. |
| Starting, reading and cancelling runs; records; usage | An API key. |
| Signing up, logging in, and managing keys | The console's own session — see below. |
What a failed authentication looks like#
A request without a key is answered 401:
{
"error": {
"code": "unauthorized",
"message": "Send an API key (Authorization: Bearer <key>) or log in.",
"details": {}
}
}So is one with a key that is mistyped or has been revoked:
{
"error": {
"code": "unauthorized",
"message": "This API key is not valid.",
"details": {}
}
}The wording of message is for a person and can change; match on code. See Errors.
Keeping a key safe#
- Read it from an environment variable or a secret store. Do not commit it.
- Do not call the API with a key from a browser page: anyone who opens the page can read the key.
- If a key may have leaked, revoke it. Revoking takes effect immediately.
Console sessions#
The console does not use an API key. Signing up or logging in sets a session cookie (enrichednow_session,
HttpOnly, SameSite=Lax) that lasts 30 days, and requests that change something also carry an X-CSRF-Token header
whose value comes from GET /v1/me. Without that header such a request is answered 403 forbidden.
Key management (/v1/keys) and GET /v1/me accept only this session — a key cannot create, list or revoke keys,
and a request that tries is answered 401 unauthorized.
When a request carries both an Authorization header and the session cookie, the key is what counts, and no
X-CSRF-Token header is needed.
You do not need any of this to use the API. The session endpoints are listed in the API reference for completeness.