Skip to main content

Authentication

The Paradarum API supports two interchangeable authentication schemes. Both satisfy the default authorization policy, so any protected endpoint accepts either one — but you should send only one per request.

ModeHeaderWho uses it
API keyX-API-Key: pdm_...Automation, scripts, CMS purge plugins
Bearer JWTAuthorization: Bearer YOUR_JWTThe Paradarum panel

API key authentication (automation)​

This is the scheme to use for any server-to-server or scripted integration.

The header​

Send the raw key in the X-API-Key header. There is no scheme word — do not prefix it with Bearer.

curl -X POST https://api.paradarum.com/api/property/123/purge \
  -H "X-API-Key: pdm_XXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

:::danger Common mistake The header is X-API-Key and its value is the raw pdm_... key — not Authorization: Bearer pdm_.... Mixing the two schemes is the most frequent cause of 401 responses. :::

Key format​

PropertyValue
Prefixpdm_
Total length32 characters (pdm_ + 28 random characters)
Character setLetters, digits, and symbols such as !@#$%&*
Retrievable prefixOnly the first 8 characters (for example pdm_AbCd) are visible after creation

The raw key is shown exactly once, at creation time. The server stores only its SHA-256 hash and the 8-character prefix — it cannot show you the full value again. See Manage API keys to generate one.

Account scoping​

You never send an account ID. The server resolves your account from the key itself and injects it automatically.

:::note Cross-account access returns 404, not 403 A key can only act on properties belonging to its own account. Targeting a property ID owned by a different account returns 404 Property not found. — the API does not reveal that the property exists elsewhere. :::

No scopes, no rate limit, no expiry​

AspectBehavior
Granular scopesNone. A key grants full account-level access to every account-scoped endpoint, not just purging.
Rate limitingNone on key or purge endpoints.
ExpiryKeys do not expire on their own; they remain valid until revoked.

:::warning Treat keys like passwords Because a key has full account access and no expiry, store it in a secrets manager and revoke it the moment it is no longer needed. See the best practices in Manage API keys. :::

Validation and errors​

On each request the raw key is SHA-256 hashed and matched against stored, non-revoked keys. A successful match updates the key's LastUsedAt timestamp. An invalid, revoked, or missing key results in 401.

Bearer JWT authentication (panel)​

The Angular panel authenticates with a JSON Web Token. You can use the same flow for interactive tooling.

Logging in​

curl -X POST https://api.paradarum.com/api/Auth/Login \
  -H "Content-Type: application/json" \
  -d '{ "username": "you@example.com", "password": "secret" }'
# -> { "succeeded": true, "message": "", "data": { "Token": "YOUR_JWT", "Message": "Success" } }

The token lives at data.Token and is valid for 24 hours by default. Send it on subsequent calls.

curl https://api.paradarum.com/api/account \
  -H "Authorization: Bearer YOUR_JWT"

:::info Two-factor accounts If two-factor authentication is enabled, the login response instead returns data.RequiresTwoFactor=true plus a data.TwoFactorToken. Exchange the TOTP or recovery code at POST /api/Auth/2fa/verify to receive the full token. :::

OpenAPI note​

Only the Bearer (JWT) scheme is declared in the generated OpenAPI document at /swagger/v1/swagger.json. The X-API-Key scheme is fully implemented but is not in the spec, so an imported spec will not document key auth — that is why it is documented here by hand.

Next steps​