Authentication

API Gateway supports three authentication modes for published endpoints:

Mode	Header Sent by Caller	Primary Use Case
none (Open)	None	Public web services, open chatbots, or webhooks verified in code.
jwt	Authorization: Bearer <token>	User-authenticated applications using an OIDC identity provider (Auth0, Okta).
apikey	X-API-Key: <key>	Machine-to-machine integrations, partner access, and CLI automation.

---

1. Open Access Mode (none)

In none mode, requests reach your workload without edge credential checks.

platformctl

platformctl gateway endpoint update support-api --auth none

curl

curl -sS -X PATCH "$CAI_API/v1/projects/$CAI_PROJECT/gateway/endpoints/support-api" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"auth": {"mode": "none"}}'

Console UI

Set Authentication Mode to Open (none) on the endpoint's Access tab.

---

2. JWT Authentication (jwt)

JWT mode validates signed tokens issued by your identity provider (OIDC / OAuth2) at the API Gateway edge before forwarding requests.

Configuration requirements

• issuer: The identity provider issuer URL (e.g. https://acme.us.auth0.com/).
• jwks_uri: HTTPS URL publishing public signing keys (JWKS).
• audiences: List of target API audience strings.

platformctl

platformctl gateway endpoint update support-api --auth jwt \
  --jwt-issuer https://acme.us.auth0.com/ \
  --jwt-jwks-uri https://acme.us.auth0.com/.well-known/jwks.json \
  --jwt-audience support-api

curl

curl -sS -X PATCH "$CAI_API/v1/projects/$CAI_PROJECT/gateway/endpoints/support-api" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"auth": {"mode": "jwt",
                "jwt": {"issuer": "https://acme.us.auth0.com/",
                        "jwks_uri": "https://acme.us.auth0.com/.well-known/jwks.json",
                        "audiences": ["support-api"]}}}'

Console UI

Select Sign-in token (JWT) on the Access tab and fill in Issuer, JWKS URI, and Audience fields.

---

3. Gateway API Keys (apikey)

In apikey mode, callers must present a valid gateway key in the X-API-Key HTTP request header.

Issuing an API key

platformctl

platformctl gateway key issue support-api --name partner-acme

Output:

key id:  l8ceif3eh18p
name:    partner-acme
expires: 2026-11-13 09:22 UTC

key (shown once):
gwk_l8ceif3eh18p_8V2V3PFuKq7ZmT4xN1sJdR6cB0wYhLgA

curl

curl -sS -X POST "$CAI_API/v1/projects/$CAI_PROJECT/gateway/endpoints/support-api/keys" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"display_name": "partner-acme"}'

Expected response (201 Created):

{
  "key": {"key_id": "l8ceif3eh18p", "display_name": "partner-acme", "state": "live"},
  "secret": "gwk_l8ceif3eh18p_8V2V3PFuKq7ZmT4xN1sJdR6cB0wYhLgA"
}

Console UI

1. Navigate to the endpoint's Access tab.
2. Click Issue API Key.
3. Copy the generated key value and save it securely.

Key Lifecycle: Rotation and Revocation

• Rotation: Mints a new key while maintaining the previous key during an overlap window (e.g. 24 hours) for seamless client updates.
• Revocation: Immediately invalidates a key at the Gateway edge.

platformctl

Rotate an existing key:

platformctl gateway key rotate support-api l8ceif3eh18p

Revoke a key:

platformctl gateway key revoke support-api l8ceif3eh18p

curl

# Rotate key
curl -sS -X POST "$CAI_API/v1/projects/$CAI_PROJECT/gateway/endpoints/support-api/keys/l8ceif3eh18p/rotate-credential" \
  -H "Authorization: Bearer $CAI_TOKEN"

# Revoke key
curl -sS -X DELETE "$CAI_API/v1/projects/$CAI_PROJECT/gateway/endpoints/support-api/keys/l8ceif3eh18p" \
  -H "Authorization: Bearer $CAI_TOKEN"

Console UI

Click Rotate or Revoke next to any active key row on the Access tab.

---

Request header processing

When requests pass through an apikey-protected endpoint:

• X-API-Key: Stripped by the API Gateway prior to forwarding traffic to your backend workload.
• X-CAI-Key-Id: Added by the API Gateway so your application code can identify the key owner without handling credential values.

---

Fail-closed security design

If configured authentication parameters cannot be verified or all API keys expire/revoke, the Gateway enforces a fail-closed policy: traffic is denied with HTTP 401/403 errors and never reaches backend workloads.