Authentication

Sending the API Key

Every API request must include a valid API key. There are two ways to send it.

The preferred way is the Authorization header with the Bearer scheme:

text

Authorization: Bearer YOUR_API_KEY

The second way is the X-API-Key header:

text

X-API-Key: YOUR_API_KEY

An API key starts with idp_live_, followed by 32 hexadecimal characters (the digits 0 to 9 and the letters a to f). The full key is shown only once, at the moment you create it.

Example request:

bash

curl -s "https://api.idparse.com/v1/quota" \
  -H "Authorization: Bearer YOUR_API_KEY"

Note

Send only one of the two headers. If you send both, they must carry the same key.

Authentication Errors

Situation	HTTP Status	Error Code
The key is missing or wrong	401	`invalid_api_key`
The two headers carry two different keys	401	`conflicting_credentials`
The key is deactivated, the account is suspended, or the email address is not verified	403	`inactive_account`

If the API key is missing or invalid, the API returns a 401 error:

json

{
    "success": false,
    "error": {
        "type": "https://idparse.com/errors/invalid-api-key",
        "code": "invalid_api_key",
        "title": "Invalid API Key",
        "status": 401,
        "detail": "The API key provided is missing or invalid."
    }
}

See Error Handling for the full error format. Requests that fail authentication are never charged.

Calls From a Browser

The API allows CORS requests (cross-origin requests, calls that a web page sends to another domain) from any origin. This is a technical permission only.

Important

Never place an API key in browser code. Everyone who opens your page can read it. Call the API from your own server, and let your web page talk to your server.

Security Best Practices

Never expose your API key in client-side JavaScript, mobile app source code, or public Git repositories.
Use environment variables or a secrets manager to store your key.
Rotate your API key periodically from the API Keys page.
Use separate keys for development and production.
Monitor your usage on the Dashboard to detect unauthorized use.