Authentication Methods
Zerq supports five authentication types for client profiles. Choose based on how callers obtain identity and what level of assurance you need.
Comparison
| Auth Type | Mechanism | Required Headers | Token Source | When to Use |
|---|---|---|---|---|
| token | Zerq-issued opaque bearer token | X-Client-ID, X-Profile-ID, Authorization: Bearer <token> | Zerq generates at profile creation or rotation | Simple server-to-server; no IdP dependency |
| jwt | HMAC-signed JWT validated by Zerq | X-Client-ID, X-Profile-ID, Authorization: Bearer <jwt> | Client signs each request with client secret | Short-lived claims, stateless validation |
| oidc | RSA-signed ID token from an external IdP | X-Client-ID, X-Profile-ID, Authorization: Bearer <id_token> | Identity provider (e.g. Keycloak) issues tokens | Enterprise SSO, role-aware auth via IdP |
| mtls | Client TLS certificate validated at the gateway | X-Client-ID, X-Profile-ID (no Authorization header needed) | Client presents certificate in TLS handshake | Machine-to-machine with certificate infrastructure |
| none | No authentication check | X-Client-ID, X-Profile-ID | N/A | Open/internal endpoints, health checks |
Decision guide
Use token when:
- The caller is a server-side service you control
- You want Zerq to manage credentials with no external IdP
- Simplicity is more important than short token lifetimes
Use jwt when:
- You need short-lived tokens (set expiry in minutes or hours)
- The caller can sign JWTs using HMAC (HS256)
- You want to embed custom claims (e.g.
role,tenant_id) in the token
Use oidc when:
- Your organization has an identity provider (Keycloak, Auth0, Okta, Azure AD)
- You want tokens to carry RSA-signed identity assertions
- Single sign-on is required across multiple services
Use mtls when:
- You need strong machine identity at the TLS layer
- Certificate rotation and revocation are already part of your infrastructure
- Regulated environments require mutual authentication (PCI-DSS, HIPAA)
Use none when:
- The endpoint is intentionally public (e.g. health check, webhook receiver)
- The service is on a trusted internal network not exposed externally
- You need a temporary bypass during development (never use in production for sensitive endpoints)
Status code mapping
| Code | Cause | Auth types affected |
|---|---|---|
401 Unauthorized | Token missing, expired, or invalid signature | token, jwt, oidc |
401 | OIDC token issued by wrong IdP | oidc |
401 | JWT signature validation failed | jwt |
403 Forbidden | Valid identity, but access denied (wrong collection, inactive profile, IP blocked) | all |
405 Method Not Allowed | Profile allowed_methods restriction | all |
429 Too Many Requests | Policy rate limit or quota exhausted | all |
Auth method guides
Related docs
- Profiles — create and manage auth configuration per client
- Credentials — backend secrets (separate from client auth)
- Profiles and Auth Headers — consumer-side header reference