Docparser.dev Docs

Documentation search

Find an answer

Start typing to search the documentation.
    Back to website Open portal

    Available

    Authentication

    Authenticate API calls, protect credentials, restrict source IPs, and rotate keys safely.

    Updated 2026-07-28

    Docparser authenticates every public API request with two headers. API keys belong to an organization and also carry the registered base URL used for webhook delivery.

    Required headers

    Send both headers on every request to https://app.docparser.dev/api/v1:

    • x-client-id: the public identifier for the API key.
    • x-client-secret: the plaintext secret shown only when the key is created.
    shell 
    curl 'https://app.docparser.dev/api/v1/documents/inv-4471' \
--header "x-client-id: $DOCPARSER_CLIENT_ID" \
--header "x-client-secret: $DOCPARSER_CLIENT_SECRET"

    If either header is absent or empty, the API returns 401 with Missing x-client-id or x-client-secret headers. An unknown or revoked client ID, a wrong secret, and a key whose organization no longer exists all return the same 401 message: Invalid client_id or client_secret. This identical invalid-credential response avoids revealing which credential check failed.

    How secrets are stored

    The portal returns the plaintext secret once. Docparser stores a bcrypt hash with work factor 10 and authenticates by comparing the supplied secret with that hash; the original secret cannot be retrieved from the stored value.

    Use separate keys for development, staging, and production so each environment can be rotated or revoked independently.

    IP allowlisting

    An API key can optionally allow exact IP addresses and CIDR ranges. An empty allowlist means the key has no source-IP restriction. When a valid key is used from an address outside a configured allowlist, the API returns 403 with error code ip_not_allowed and identifies the rejected address and key name.

    Credential validation happens before the IP check. Invalid credentials therefore retain the identical 401 response and do not reveal whether an allowlist exists.

    Revocation

    Revoking a key takes effect immediately for new requests. Revoked keys are excluded during credential lookup and receive 401 Invalid client_id or client_secret. Existing jobs continue to use the key association stored on their persisted rows; revocation prevents new authenticated API calls.

    Rotate without downtime

    Use an add-then-revoke rotation:

    1. Create a new key for the same organization, webhook base URL, and IP allowlist.
    2. Store the new secret in your secret manager.
    3. Deploy the new client ID and secret to every caller.
    4. Confirm requests succeed with the new key and no callers still use the old one.
    5. Revoke the old key.

    Because an organization can have several active keys, the old and new keys can overlap during the rollout. Do not revoke the old key until the new deployment is verified.