Skip to main content
⚠️ APIv1 WILL BE DECOMMISSIONED DECEMBER 31, 2026 | 🟢 APIv2 IS LIVE AND MIGRATION-READY

Authentication - APIv2

Updated

Every request to the Propelus API must be authenticated with two header credentials. There are no unauthenticated endpoints.

Developer Docs: 

https://propelus.com/developer/getting-started/authentication

 

Required headers

Send both headers on every request:

Header Description
x-api-key Your secret API key. Treat it like a password.
x-client-id Your client identifier. Also used to scope webhook signatures.

Both are required together. A request missing either header, or sending an invalid value, is rejected before any processing happens.

Send the header names in lowercase, exactly as shown. Over HTTP/1.1, a mixed-case X-Client-Id fails with 403 restricted_access, and a mixed-case X-Api-Key fails with 401 invalid_credentials, even when the values are correct. Both responses use the standard error envelope. Some HTTP clients rewrite header names this way; for example, Python's urllib always sends X-Client-Id. Over HTTP/2, header names are always lowercase.

curl https://api.propelus.com/v2/professions \  
  -H "x-api-key: $PROPELUS_API_KEY" \  
  -H "x-client-id: $PROPELUS_CLIENT_ID"

 

Getting credentials

Propelus shares your x-api-key and x-client-id with you in a secure manner. These credentials grant access to both the Demo and Production environments. See Environments for the base URLs each environment uses.

Contact support@propelus.com to request or troubleshoot credentials.

 

Authentication failures

The response depends on which header failed.

Missing or invalid x-api-key. The request is rejected with 403 before it reaches the API. The body is not the standard error envelope; it contains a single message field:

{
  "message": "<error message>"
}

Valid x-api-key, but x-client-id is missing, unknown, or doesn't match the key. The API returns 401 or 403 with the standard error envelope:

{
  "status": 401,
  "detail": "Unauthorized",
  "code": "invalid_credentials"
}
  • 401 with code: invalid_credentials means the x-client-id is missing or doesn't match the x-api-key, or x-api-key was sent with a mixed-case name such as X-Api-Key (see Required headers).
  • 403 with code: restricted_access means the x-client-id isn't recognized or isn't authorized for the resource, or x-client-id was sent with a mixed-case name such as X-Client-Id (see Required headers).
  • When the envelope is present, code is stable and safe to branch on; the detail message is human-readable and may change.

In every case, verify you are sending both x-api-key and x-client-id, with lowercase header names and the values Propelus shared with you.

See the full list of error codes in the Errors reference.

Keeping credentials safe

  • Never ship keys to a browser or mobile client. Call the Propelus API only from your backend; a key embedded in client-side code is exposed to anyone who loads the page.
  • Store keys in a secret manager or environment variables, not in source control.
  • Rotate a key immediately if it is exposed. Contact support@propelus.com to rotate credentials.

 

Related articles