Authentication

Send your API key as a bearer token on every request:

curl "$BASE/v1/async/task/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

A missing or wrong key returns 401:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

Which endpoints require it

Endpoint	Auth
`POST /v1/async/task`	Bearer
`POST /v1/async/task/batch`	Bearer
`GET /v1/async/task/{id}`	Bearer
`GET /stats`	Bearer
`GET /capacity`	Bearer
`GET /health`	None — liveness probe
`GET /ready`	None — readiness probe

The service also exposes /internal/* routes used by its own Pub/Sub push subscription and Cloud Scheduler jobs. They authenticate with a separate internal token, are not part of the client contract, and are not documented here.

Key management

There is a single static token shared by all clients. It lives in Google Secret Manager under pplx-server-api-key and is compared verbatim by the server. To rotate, add a new secret version and redeploy so the service picks it up:

KEY=$(openssl rand -base64 32)
printf '%s' "$KEY" | gcloud --project=anymorph-prompting \
  secrets versions add pplx-server-api-key --data-file=-

Rotation is not zero-downtime. The server accepts exactly one key at a time, so clients must cut over as the new revision rolls out. If you need overlapping validity, the server must first be changed to accept a comma-separated key list.

Reading the secret requires roles/secretmanager.secretAccessor scoped to pplx-server-api-key.

Quickstart Async tasks

Get started

Core concepts

Engines

Migrating

Which endpoints require it

Key management

​Which endpoints require it

​Key management

Which endpoints require it

Key management