dotfiles/.agents/skills/cloudflare-deploy/references/secrets-store/api.md

API Reference

Binding API

Basic Access

CRITICAL: Async .get() required - secrets NOT directly available.

.get() throws on error - does NOT return null. Always use try/catch.

interface Env {
  API_KEY: { get(): Promise<string> };
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const apiKey = await env.API_KEY.get();
    return fetch("https://api.example.com", {
      headers: { "Authorization": `Bearer ${apiKey}` }
    });
  }
}

Error Handling

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    try {
      const apiKey = await env.API_KEY.get();
      return fetch("https://api.example.com", {
        headers: { "Authorization": `Bearer ${apiKey}` }
      });
    } catch (error) {
      console.error("Secret access failed:", error);
      return new Response("Configuration error", { status: 500 });
    }
  }
}

Multiple Secrets & Patterns

// Parallel fetch
const [stripeKey, sendgridKey] = await Promise.all([
  env.STRIPE_KEY.get(),
  env.SENDGRID_KEY.get()
]);

// ❌ Missing .get()
const key = env.API_KEY;

// ❌ Module-level cache
const CACHED_KEY = await env.API_KEY.get(); // Fails

// ✅ Request-scope cache
const key = await env.API_KEY.get(); // OK - reuse within request

REST API

Base: https://api.cloudflare.com/client/v4

Auth

curl -H "Authorization: Bearer $CF_TOKEN" \
  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/secrets_store/stores

Store Operations

# List
GET /accounts/{account_id}/secrets_store/stores

# Create
POST /accounts/{account_id}/secrets_store/stores
{"name": "my-store"}

# Delete
DELETE /accounts/{account_id}/secrets_store/stores/{store_id}

Secret Operations

# List
GET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets

# Create (single)
POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
{
  "name": "my_secret",
  "value": "secret_value",
  "scopes": ["workers"],
  "comment": "Optional"
}

# Create (batch)
POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
[
  {"name": "secret_one", "value": "val1", "scopes": ["workers"]},
  {"name": "secret_two", "value": "val2", "scopes": ["workers", "ai-gateway"]}
]

# Get metadata
GET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}

# Update
PATCH /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
{"value": "new_value", "comment": "Updated"}

# Delete (single)
DELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}

# Delete (batch)
DELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
{"secret_ids": ["id-1", "id-2"]}

# Duplicate
POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}/duplicate
{"name": "new_name"}

# Quota
GET /accounts/{account_id}/secrets_store/quota

Responses

Success:

{
  "success": true,
  "result": {
    "id": "secret-id-123",
    "name": "my_secret",
    "created": "2025-01-11T12:00:00Z",
    "scopes": ["workers"]
  }
}

Error:

{
  "success": false,
  "errors": [{"code": 10000, "message": "Name exists"}]
}

TypeScript Helpers

Official types available via @cloudflare/workers-types:

import type { SecretsStoreSecret } from "@cloudflare/workers-types";

interface Env {
  STRIPE_API_KEY: SecretsStoreSecret;
  DATABASE_URL: SecretsStoreSecret;
  WORKER_SECRET: string; // Regular Worker secret (direct access)
}

Custom helper type:

interface SecretsStoreBinding {
  get(): Promise<string>;
}

// Fallback helper
async function getSecretWithFallback(
  primary: SecretsStoreBinding,
  fallback?: SecretsStoreBinding
): Promise<string> {
  try {
    return await primary.get();
  } catch (error) {
    if (fallback) return await fallback.get();
    throw error;
  }
}

// Batch helper
async function getAllSecrets(
  secrets: Record<string, SecretsStoreBinding>
): Promise<Record<string, string>> {
  const entries = await Promise.all(
    Object.entries(secrets).map(async ([k, v]) => [k, await v.get()])
  );
  return Object.fromEntries(entries);
}

See: configuration.md, patterns.md, gotchas.md