Secrets

When a function needs a credential — a third-party API key, a webhook signing secret, your own developer token — set it as a secret and read it from env inside the handler. Secrets are encrypted at rest and synced to the runtime within seconds. Plaintext is never returned: once set, you can see a secret's name and sync status, but never its value.

A secret is either function-scoped (bound to one function) or project-wide (shared by every function in the project). Project-wide is the default — omit the function and one value reaches every function, including ones you deploy later. Scope to a single function when only that function should see the value.

You may use the same name at both scopes. The function-scoped value is the explicit override for that function; every other function receives the project-wide default. Sync and deploy ordering does not change that precedence.

The everyday path is the CLI (amba secrets set NAME value) and the amba_secrets_* MCP tools. The REST surface below is what both wrap; routes mount under /v1/admin/projects/:projectId/secrets.

Set a secret

Omit the function for a project-wide secret — every function in the project sees it:

amba secrets set OPENAI_API_KEY sk-…

Add --function to scope it to one function:

amba secrets set STRIPE_API_KEY sk_live_… --function checkout

Or via REST — include function to scope, omit it for project-wide:

# Project-wide
curl -X POST 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/secrets' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "OPENAI_API_KEY", "value": "sk-…" }'
 
# Function-scoped
curl -X POST 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/secrets' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "STRIPE_API_KEY", "value": "sk_live_…", "function": "checkout" }'

For a project-wide secret, function comes back null:

{
  "data": {
    "name": "OPENAI_API_KEY",
    "function": null,
    "version": 1,
    "version_path": "…",
    "sync_status": "pending",
    "created_at": "2026-05-27T10:00:00.000Z"
  }
}

Setting a secret that already exists writes a new version and re-syncs. The function picks up the new value once sync_status flips to synced (typically under 30 seconds).

Set before you deploy

You don't need an existing deployment to set a secret. Set everything your functions will need first, then deploy once — the sync drains as soon as the deployment lands, and amba functions deploy re-syncs at the end of a deploy to pick up anything set in the meantime. This works for both project-wide and function-scoped secrets.

# Set all your secrets up front…
amba secrets set OPENAI_API_KEY sk-…
amba secrets set STRIPE_API_KEY sk_live_… --function checkout
 
# …then deploy. The values are already waiting.
amba functions deploy ./functions/checkout.ts

Rules

• Secret name must match ^[A-Z][A-Z0-9_]{0,62}$ (uppercase env-var shape).
• Function name, when given, must match ^[a-z][a-z0-9_-]{0,57}$. Omit it for a project-wide secret. The function does not need to be deployed yet — secrets can be set before deploy.
• Value cap is 64 KiB.
• The complete AMBA_ and EDGE_ namespaces are platform-managed and rejected with RESERVED_BINDING. The exact names STORAGE and EDGE_DB_PROXY are also reserved. Use an app-specific prefix such as PODPOD_ for your own secrets.

Read it in a function

The platform injects each secret as an env binding under its name:

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const res = await fetch('https://api.stripe.com/v1/charges', {
      headers: { Authorization: `Bearer ${env.STRIPE_API_KEY}` },
      // …
    });
    return new Response(await res.text(), { status: res.status });
  },
};
 
interface Env {
  STRIPE_API_KEY: string; // injected from the secret above
}

See Runtime for the full list of env bindings.

List and inspect

GET /secrets returns every secret on the project — name, function, version, and sync status. Project-wide secrets come back with function set to null. Plaintext is never included (there is no read-back endpoint). Filter to one function with ?function=.

curl 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/secrets?function=checkout' \
  -H 'Authorization: Bearer $AMBA_PAT'

{
  "data": [
    {
      "function": "checkout",
      "name": "STRIPE_API_KEY",
      "version": 2,
      "sync_status": "synced",
      "attempts": 1,
      "last_error": null,
      "updated_at": "2026-05-27T10:00:30.000Z"
    }
  ]
}

sync_status is one of pending, syncing, sync_failed_retrying, synced, revocation_pending, revoking, or revoke_failed_retrying. A non-null last_error plus a retrying status points at an operation that's still being retried.

Delete

Pass --function (CLI) / ?function= (REST) to delete a function-scoped secret; omit it to delete the project-wide secret of that name:

# Function-scoped
amba secrets unset STRIPE_API_KEY --function checkout
 
# Project-wide
amba secrets unset OPENAI_API_KEY

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/secrets/STRIPE_API_KEY?function=checkout' \
  -H 'Authorization: Bearer $AMBA_PAT'

Delete removes the value from the backing store immediately and durably queues runtime-binding revocation for every affected Worker script. Provider failures retry automatically; the control row stays visible with a revocation status until every binding is gone. Delete is idempotent; removing a secret that's already gone also rechecks runtime bindings and succeeds.

When both scopes use the same name, deleting the function override restores the project-wide default on that function. Deleting the project-wide default keeps each surviving function override in place.

Endpoints

MCP tools