Profiles and Auth Headers

Every request through the Zerq gateway must include the correct profile headers. This page explains what each header does, where to find the values, and which additional headers each authentication type requires.

Required headers for every request

Header	Description	Where to find it
X-Client-ID	Identifies the client (application/team)	Client detail page in the Management UI or Developer Portal
X-Profile-ID	Identifies the profile (auth configuration)	Profile detail page, or the auth headers panel in the Developer Portal
Authorization	Required by most auth types (see table below)	Generated when the profile is created; copy from profile detail

---

Authentication type requirements

Auth Type	X-Client-ID	X-Profile-ID	Authorization	Notes
token	Required	Required	Bearer <token>	Server-to-server. Token is static until rotated.
jwt	Required	Required	Bearer <jwt>	Short-lived HMAC-signed JWT. Client generates and signs each request.
oidc	Required	Required	Bearer <id_token>	Token issued by your identity provider (e.g. Keycloak).
mtls	Required	Required	Not required	Client presents a certificate at TLS layer. No Authorization header needed.
none	Required	Required	Not required	Open access. No token validation.

---

Example requests

Token authentication

curl -X GET "https://gateway.example.com/payments/v1/charge" \
  -H "X-Client-ID: cl_abc123" \
  -H "X-Profile-ID: pr_xyz456" \
  -H "Authorization: Bearer zerq_tok_xxxxxx"

JWT authentication

curl -X GET "https://gateway.example.com/payments/v1/charge" \
  -H "X-Client-ID: cl_abc123" \
  -H "X-Profile-ID: pr_xyz456" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

OIDC authentication

curl -X GET "https://gateway.example.com/payments/v1/charge" \
  -H "X-Client-ID: cl_abc123" \
  -H "X-Profile-ID: pr_xyz456" \
  -H "Authorization: Bearer <oidc-id-token>"

None (open endpoint)

curl -X GET "https://gateway.example.com/health/status" \
  -H "X-Client-ID: cl_abc123" \
  -H "X-Profile-ID: pr_xyz456"

---

Where to find your credentials

In the Management UI:

1. Go to Access Control → Clients and open your client.
2. Open the profile you want to use.
3. Click Show Credentials to reveal the token (one-time display after creation, or after rotation).
4. Use the copy buttons to copy X-Client-ID, X-Profile-ID, and Authorization header values.

In the Developer Portal:

1. Sign in to the Developer Portal.
2. From the collection detail page, the Auth Headers panel shows all three header values with individual copy buttons.

---

Status codes

Code	Meaning	What to check
401	Authentication failed	Token expired, wrong header format, JWT signature invalid, OIDC token from wrong issuer
403	Access denied	Client not assigned to this collection, profile inactive, IP address not on allowlist
405	Method not allowed	Profile allowed_methods restriction — profile only allows GET but you sent POST
429	Rate limit exceeded	Policy rate limit or quota is exhausted for this client

---

Related docs

• Authentication Methods — compare token, JWT, OIDC, mTLS, and none in detail
• Troubleshooting — full diagnosis table for common errors
• Profiles — how admins create and manage profiles