API tokens

The gRPC door authenticates every caller with a scoped API token, presented as an authorization: Bearer <token> metadata entry or HTTP header. Tokens live in the database rather than in the environment, which is what makes each of the next three sentences true: one can be revoked without touching any other, one can be granted less than the whole surface, and one carries a record of when it was last used.

Minting the first one

Mint it wherever the server can reach its database. No listener has to be running — provisioning a credential is not a role, so the command configures itself from FLEXIQ_DSN, FLEXIQ_BACKEND and FLEXIQ_NAMESPACE alone:

export FLEXIQ_DSN=postgres://user:pass@host/db
export FLEXIQ_NAMESPACE=prod

flexiq-server token create --name my-producer --scope produce

It prints the token to stdout, once:

fqt_9f2c1ab74e05d366.mZ1qgWx8yQ4nR7t0KcV2sJdH6bPfLuA3eXyN5rTiOk

That is the only time it is shown. What the server stores is a SHA-256 digest of the secret half, so the token is not recoverable from the row, from a database dump, or by anyone with admin access. If it is lost, revoke it and mint another.

The token is the only thing on stdout — the confirmation, which carries the id, goes to stderr — so a command substitution captures the credential and nothing else:

export FLEXIQ_TOKEN=$(flexiq-server token create --name my-producer --scope produce)

Point it at the same database the server reads. A token minted against another one is minted somewhere nothing checks it, and the door it was meant for will refuse every call made with it.

On Kubernetes, the same command through the running release:

kubectl exec deploy/flexiq-flexiq-server -- \
  flexiq-server token create --name my-producer --scope produce

The dashboard does the same three things under Configuration → gRPC tokens, behind its existing admin role — minting is an operator action, and a producer credential must never be able to mint itself a wider one. Automation that has no dashboard session mints over the admin door's token methods instead, with a token carrying the tokens scope, and can only mint what that token already holds.

Scopes

A token grants scopes. They are not a hierarchy, with one exception: produce also opens everything read does, because it always has.

A producer and an executor need opposite permissions, so a token that can poll for work cannot enqueue it, and a produce token asked for an executor RPC is refused with PERMISSION_DENIED and the reason SCOPE_DENIED, carrying the scope it lacked in the error metadata. Repeat --scope to grant several, and grant each only to something that genuinely needs it.

The producer and operator packages are split by method rather than granted whole: a method that declares idempotency_level = NO_SIDE_EFFECTS needs read (producer) or inspect (operator), and every other one needs produce or admin. A dashboard or an alerting job that watches jobs gets read and can neither submit nor cancel. A support tool gets inspect and can change nothing. An operator's token carries both operator scopes:

flexiq-server token create --name ops --scope inspect --scope admin

produce reaches none of it, so a producer credential that leaks costs you an enqueue path rather than an operator. Token minting over gRPC needs the separate tokens scope, and the settings store and webhook secrets stay behind the dashboard's session and role check — they are on no gRPC surface at all. The admin door is the page for what inspect, admin and tokens reach.

The table is about calls, not about the schema. Server reflection asks only that a caller be authenticated, so any row above reads every package — a produce token can describe the executor RPCs it will then be refused. The gRPC door's Reflection, and what it hands out has the shape of that, and why revoking is the control rather than scoping.

Narrowing a token to queues and tasks

Any grant but tokens can be narrowed to some queues, some tasks, or both. This is how you give a webhook receiver or an untrusted edge service a token that can enqueue exactly one task and nothing else:

flexiq-server token create --name receipts-webhook \
  --scope 'produce:queue=emails,task=send_receipt'

A grant is <scope>:queue=<pattern>,task=<pattern>, and either qualifier can be left out. A pattern is an exact name, a prefix ending in * (emails-*), or * for every name. * anywhere else is refused, and so are commas, = and whitespace. Repeat --scope to hold several grants. A call is allowed when any one of them covers it:

flexiq-server token create --name billing-support \
  --scope 'read:queue=billing' \
  --scope 'produce:queue=billing,task=refund'

The dashboard's token dialog has the same two fields, and they narrow every scope switch.

What a narrowed producer token gets, call by call:

Two more of those are refusals worth knowing about:

• A unique_key is matched across the whole namespace, so an enqueue can be deduplicated to an existing job in another queue. When that job is outside a narrowed token's grants, the enqueue is refused rather than handing the job back. Nothing was written.
• A debounce key is matched across the namespace too, and a debounced enqueue that coalesces moves an existing job's deadline, or replaces its payload. A narrowed token cannot see which job that would be, so it cannot debounce at all.

One effect crosses the boundary on purpose. Cancelling a job cancels the pending jobs that depend on it, in whatever queue they sit, exactly as it does for any token. Whoever enqueued the dependent chose that edge. A job whose dependency is cancelled could never run anyway, and it would be cancelled the same way if the dependency had failed. Refusing the cancel instead would let a job in another queue stop a narrowed token from cancelling its own work.

The JSON facade calls the same handlers, so it gives the same answers — 403 for a refusal and 404 for a hidden job.

Every token minted before narrowing existed keeps exactly what it had. A grant is stored in the same list as the scope names always were. A server older than this one drops a narrowed grant it cannot read, so rolling back can only take access away from a narrowed token, never widen it.

Narrowing an executor

An executor token can be held to the tasks it was built to run:

flexiq-server token create --name mailer-executor \
  --scope 'execute:queue=emails,task=send_*'

The executor names its tasks when it attaches, and the server checks that list before anything is registered. It names no queue, so a queue qualifier is enforced when work is placed instead: a job on a queue the grants do not reach waits for an executor whose grants do, and fails back for a retry if none does.

Grants bind only the gRPC door. An executor attached over the socket listener (FLEXIQ_LISTEN) presents the shared FLEXIQ_ATTACH_TOKEN, which carries no grants, and may run any task it declares.

Narrowing an operator

An operator token can be held to one team's queues. This one can pause and resume billing, read and replay its dead letters, and manage the schedules that fire into it, and it can touch nothing else:

flexiq-server token create --name billing-ops \
  --scope 'inspect:queue=billing' --scope 'admin:queue=billing'

Each operator method is checked against what it acts on:

As on the producer door, a listing is filtered by the query, never after the page is cut. The filters are optional for an unnarrowed token. In fq, they are --queue and --task on fq dlq list, fq periodic list and fq overrides list, and --queue on fq throughput.

One namespace, fixed at mint time

A token is bound to the namespace the minting process itself serves, and it is refused by a listener serving another. There is no namespace field on the wire in any RPC, in either package: the namespace comes from the credential and nowhere else.

That is why flexiq-server token create reads FLEXIQ_NAMESPACE and takes no --namespace argument. A credential for a namespace this deployment does not schedule would accept enqueues that nothing ever dequeues — a success response, and no work.

Listing

flexiq-server token list

ID                 NAME                     STATUS     NAMESPACE        EXPIRES    SCOPES
9f2c1ab74e05d366   my-producer              active     prod             87d        produce
b1d0e7c4a3f29855   ci-executor              active     prod             12d        execute

The id is public — it is what a listing shows, what revoke takes, and the part of the token before the dot — so it is safe in a log or a ticket. STATUS is active, expired or revoked; a revoked row is kept, because it is the record that the credential existed, who minted it and when it was last used.

--all-namespaces widens the listing past the one this process serves. Without it, a token belonging to another namespace reads as absent rather than as a refusal — the same answer revoke gives, so neither command can be used to probe for the existence of another tenant's credentials.

Expiry

Every token expires. The default is 90 days and the maximum is 365 — a credential with no end date is a permanent one with extra steps — and a request for longer is refused rather than quietly clamped:

flexiq-server token create --name nightly-batch --scope produce --expires-in-days 30

Once a token is inside 30, 20 and 10 days of expiry, the server logs a warning the first time it is used at each threshold. Warning on use rather than on a timer means the credentials that get a reminder are the ones actually carrying traffic, and one that expires unnoticed was one nothing was calling with.

Rotating

There is no rotate command, because rotation is two commands and an interval you choose:

# 1. Mint the replacement, alongside the one still in use.
flexiq-server token create --name my-producer-2026-09 --scope produce

# 2. Roll your clients onto it. Both work for as long as this takes.
# 3. Revoke the old one.
flexiq-server token revoke 9f2c1ab74e05d366

Nothing restarts at any point. The door reads the row per call rather than caching a verdict, so both a new token and a revocation take effect on the next call, everywhere, including on replicas you did not touch.

Check last_used_at before step 3, not after. The dashboard's token table has the column; it is the only thing that tells you whether a client you forgot is still presenting the credential you are about to revoke. It is written at most once per token per minute, so treat it as "used recently", not as a precise timestamp.

Revoking

flexiq-server token revoke 9f2c1ab74e05d366

A revoked token fails on its next call, with no restart. A revocation from the dashboard, from another pod, or from a shell takes effect immediately everywhere, because there is no cache to invalidate — a cached allow would be a revocation that never takes effect.

What the token did while it was valid is in the audit trail, under the same id. So are its mint and its revoke — from the dashboard under the user who did it, from the shell as cli — as records targeting token:<id>:

fq audit list --token-id 9f2c1ab74e05d366 --all    # what it did
fq audit list --target token:9f2c1ab74e05d366      # who minted and revoked it

On the dashboard, What this token did in a token's row menu opens the same trail, filtered to the token — see From the dashboard.

What a refusal tells a caller

Nothing it does not already know. A missing token, a wrong one, a well-formed token for an id that was never minted, one under the wrong scheme, an expired one, a revoked one, one minted for another namespace, and a call to an RPC that does not exist all answer UNAUTHENTICATED with the reason UNAUTHENTICATED and the same message.

That is deliberate on both counts: a distinguishable answer tells a client guessing tokens which guess was closer, and a path answered before authentication tells it which services the build carries. There are two exceptions. The two grpc.health.v1 RPCs answer without a credential — see The gRPC door for why a probe cannot carry a credential. And the KEDA external scaler reads its token from the request body, so a tokenless body over its 64 KiB cap is refused with OUT_OF_RANGE, and one that does not decode with a decode error, before that token is checked; every scaler request that decodes is authenticated first.