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.

```typescript
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

```typescript
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

```typescript
// 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

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

### Store Operations

```bash
# 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

```bash
# 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:
```json
{
  "success": true,
  "result": {
    "id": "secret-id-123",
    "name": "my_secret",
    "created": "2025-01-11T12:00:00Z",
    "scopes": ["workers"]
  }
}
```

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

## TypeScript Helpers

Official types available via `@cloudflare/workers-types`:

```typescript
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:

```typescript
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](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)