Skip to the content
EnrichedNowDocs

    Type to search every page.

    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.

    Shell
    curl "https://api.enrichednow.com/v1/runs" \
      -H "Authorization: Bearer $ENRICHEDNOW_API_KEY"

    API keys#

    Formaten_live_ followed by 32 or more URL-safe characters
    HeaderAuthorization: Bearer <key>
    CreatedIn the console, under API keys
    ShownOnce, when the key is created
    Stored by usAs 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#

    EndpointsAuth
    GET /v1/health, GET /v1/scrapers, GET /v1/scrapers/{id}None. The catalogue is public.
    Starting, reading and cancelling runs; records; usageAn API key.
    Signing up, logging in, and managing keysThe console's own session — see below.

    What a failed authentication looks like#

    A request without a key is answered 401:

    401 · JSON
    {
      "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:

    401 · JSON
    {
      "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.