Token Vault

When you create tasks that call third-party APIs (AI providers, payment gateways, internal services), you typically need to pass API keys or bearer tokens in the request headers. The Token Vault lets you store those credentials once and reference them by a safe tok_* identifier, so raw secrets never appear in your task payloads.

Why use the Token Vault?

Without the vault, your API keys sit in every task you create:

{
  "targetUrl": "https://api.openai.com/v1/chat/completions",
  "headers": {
    "Authorization": "Bearer sk-proj-abc123-real-secret-key"
  }
}

This means your third-party credentials are stored alongside task data. If you create thousands of tasks, that secret appears thousands of times.

With the vault, you store the credential once and reference it by ID:

{
  "targetUrl": "https://api.openai.com/v1/chat/completions",
  "headers": {
    "Authorization": "tok_01jrx7m2k..."
  }
}

The actual credential is encrypted at rest and only decrypted at the moment your task executes. It is never stored in the task record.

How it works

1. Store once - Call POST /v1/tokens with your credential. You receive a tok_* reference ID.
2. Reference in tasks - Use the tok_* ID in task headers where you would normally put the raw value.
3. Validated at creation - When you create a task, AsyncQueue checks that each tok_* reference exists and belongs to your team.
4. Resolved at execution - When the task runs, the tok_* reference is replaced with the real credential before the HTTP call is made.
5. Cleaned from memory - After execution, the decrypted credential is cleared from memory.

Quick start

Step 1: Store your credential

curl -X POST https://api.asyncqueue.io/v1/tokens \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fal.ai Production Key",
    "value": "your-fal-api-key-here"
  }'

Response:

{
  "token": {
    "id": "tok_01jrx7m2k...",
    "name": "fal.ai Production Key",
    "createdAt": "2026-04-09T14:00:00.000Z"
  }
}

Save the tok_* ID. The raw value is never returned again.

Step 2: Use it in a task

curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://queue.fal.run/fal-ai/flux/dev",
    "provider": "fal",
    "headers": {
      "Authorization": "tok_01jrx7m2k...",
      "Content-Type": "application/json"
    },
    "body": "{\"prompt\": \"a beautiful sunset over mountains\"}"
  }'

Only the Authorization header value is resolved from the vault. The Content-Type header is passed through as-is because it does not start with tok_.

Step 3: Manage your tokens

# List all active tokens (metadata only, no raw values)
curl https://api.asyncqueue.io/v1/tokens \
  -H "Authorization: Bearer your-api-key"

# Revoke a token you no longer need
curl -X DELETE https://api.asyncqueue.io/v1/tokens/tok_01jrx7m2k... \
  -H "Authorization: Bearer your-api-key"

Security properties

• Encrypted at rest - Raw credentials are encrypted before storage. The database never contains plaintext secrets.
• Team isolation - Each team’s credentials are encrypted with a separate derived key. One team’s tokens cannot be decrypted with another team’s key.
• Decrypted only at execution - The raw credential exists in memory only for the duration of the HTTP call, then is cleared.
• Audit trail - Every time a vault token is created, accessed, or revoked, an audit entry is recorded with the actor and timestamp.
• Revocation - Revoking a token takes effect immediately. New tasks referencing a revoked token are rejected at creation time.

Working with AI providers

The Token Vault works seamlessly with provider templates. Store your provider API key once, then reference it across all tasks for that provider:

# Store your Replicate API key
curl -X POST https://api.asyncqueue.io/v1/tokens \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Replicate", "value": "r8_your_replicate_token"}'

# Use it with the Replicate provider template
curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://api.replicate.com/v1/predictions",
    "provider": "replicate",
    "headers": {
      "Authorization": "Bearer tok_01jrx8n3p..."
    },
    "body": "{\"version\": \"model-version-id\", \"input\": {\"prompt\": \"hello\"}}"
  }'

Polling and token forwarding

When a task enters AI provider polling mode, the vault token is also resolved for poll requests. If your provider’s polling endpoint requires authentication (controlled by the forwardAuth setting in poll config), the same tok_* reference is decrypted and forwarded to each status check.

Limits

• Token names must be 100 characters or fewer
• There is no limit on the number of vault tokens per team
• Revoked tokens cannot be un-revoked - store a new token instead

API reference

See the full Vault Tokens API reference for request/response details, error codes, and OAuth scope requirements.