For apps: the project API

What a project API key can do

Keys have no narrower scope. Within its own project, a key may do everything /v1 offers. Keys are made, revoked and rotated on the Keys page, as Security and access describes.

{ "ok": false, "error": "<one sentence for a person>", "code": "invalid",
  "fields": { "<path in the request>": "<message>" } }

Each /v1 route

Every route also answers 401 for a missing, unknown, revoked or expired key, 403 for another project's key, and 429 past the key's limits.

Create a task

The same JSON as the Create a task page. The host, project, key and target below are placeholders.

POST /v1/projects/my-app/queues/email/tasks HTTP/1.1
Host: console.example.com
Authorization: Bearer cck_<43 characters>
Content-Type: application/json

{
  "name": "welcome-email-42",
  "scheduleTime": "2026-10-23T09:00:00.000Z",
  "method": "POST",
  "url": "https://example.com/api/worker",
  "headers": { "content-type": "application/json" },
  "body": "{\"job\":\"email.send\",\"user\":42}",
  "auth": {
    "kind": "oidc",
    "serviceAccount": "my-app-tasks@my-app.cloud-console",
    "audience": "https://example.com/api/worker"
  },
  "attemptDeadline": "3m"
}

The answer is 201 { "ok": true, "task": { … } }: the task as stored, in state queued until its time. Times come back as Unix milliseconds (UTC). For the OIDC option, https://example.com must be among the service account's allowed origins.

Unknown fields are refused: 400, fields.<name>. A refusal names each field by its path, such as auth.secret or headers.X-Foo. The six auth options, and what each sends, are on Security and access.

Behaviour an app relies on

The maintenance switch

curl -fsS -X PUT "https://console.example.com/v1/projects/my-app/maintenance" \
  -H "Authorization: Bearer cck_<43 characters>" -H 'content-type: application/json' -d '{"on":true}'
# ... migrate and deploy ...
curl -fsS -X PUT "https://console.example.com/v1/projects/my-app/maintenance" \
  -H "Authorization: Bearer cck_<43 characters>" -H 'content-type: application/json' -d '{"on":false}'

How FlowDeck uses it

FlowDeck sends its background work to the console as tasks, and its timers come from scheduler jobs. Its client is createTask in its api/src/shared/jobs/job.service.ts, and the API matches it exactly.

1. FlowDeck creates a taskA POST to /v1/projects/flowdeck/queues/<queue>/tasks with its project key. Its queues are email, push, ai and timer.
   Anything but a 2xx or 409, or no answer in 10 seconds: FlowDeck runs the job itself. A task with a delay, such as a timer's follow-up, is logged and dropped instead.
2. What the task holdsA POST to FlowDeck's /api/worker with a JSON body: the job's name and a payload FlowDeck seals itself. The task may have a name and a scheduleTime in ISO 8601. Its auth is OIDC as the project's service account flowdeck-tasks, with the worker's URL as the audience.
   A missing queue answers 404, and FlowDeck runs the job itself.
3. The console checks and counts itThe key, the fields, the allowed origin and the project's daily quota.
   409: FlowDeck takes it as done. 429 quota: FlowDeck runs the job itself.
4. The queue calls FlowDeckAt the task's time, with a fresh OIDC token, within the queue's rate and retry settings.
   A failed answer is retried as the queue's settings say.
5. FlowDeck checks the tokenIts /api/worker verifies the token, sub and email included. Its verifier fetches the JWKS again for a kid it lacks.
   2xx: the task is done.

• Its setup is seeded. A database migration makes the project flowdeck, its queues, the service account and ten scheduler jobs, so none of it is made by hand. Every job is a POST to the same /api/worker with OIDC as flowdeck-tasks, in UTC, with a 60-second attempt deadline. No secret is seeded.
• Its settings, by name. CONSOLE_URL, CONSOLE_PROJECT, CONSOLE_API_KEY and CONSOLE_SERVICE_ACCOUNT. FlowDeck sends tasks to the console only when all four are set.
• Its share of the quota. The jobs run 1,417 times a day (1,418 on Sundays). That leaves about 3,580 of the default 5,000 for FlowDeck's tasks and their retries.

The OIDC token a target receives

With the OIDC option, the console signs a short-lived token for the task's service account and sends it as Authorization: Bearer <JWT>.

Tasks from a file

• The file is { "tasks": [ … ] }: 1 to 50 tasks, each the JSON of a single create, as above.
• The whole file is checked before anything is made. One problem anywhere means 400 and no tasks, with each message at its path, such as tasks.3.url.
• The quota is checked for the whole file at once. One request to the queue then makes the tasks in the file's order.
• A name the queue still remembers is refused for that task only, and its quota unit is given back.
• It writes one audit line, tasks.create. It counts one change per 10 tasks against the person's hourly budget.

The full write-up, with the page and its sample file, is Tasks from a file.

Cloud Console, as it is on main. 22 Oct 2026.