1# API Reference
2 
3## Binding API
4 
5### Basic Access
6 
7**CRITICAL**: Async `.get()` required - secrets NOT directly available.
8 
9**`.get()` throws on error** - does NOT return null. Always use try/catch.
10 
11```typescript
12interface Env {
13  API_KEY: { get(): Promise<string> };
14}
15 
16export default {
17  async fetch(request: Request, env: Env): Promise<Response> {
18    const apiKey = await env.API_KEY.get();
19    return fetch("https://api.example.com", {
20      headers: { "Authorization": `Bearer ${apiKey}` }
21    });
22  }
23}
24```
25 
26### Error Handling
27 
28```typescript
29export default {
30  async fetch(request: Request, env: Env): Promise<Response> {
31    try {
32      const apiKey = await env.API_KEY.get();
33      return fetch("https://api.example.com", {
34        headers: { "Authorization": `Bearer ${apiKey}` }
35      });
36    } catch (error) {
37      console.error("Secret access failed:", error);
38      return new Response("Configuration error", { status: 500 });
39    }
40  }
41}
42```
43 
44### Multiple Secrets & Patterns
45 
46```typescript
47// Parallel fetch
48const [stripeKey, sendgridKey] = await Promise.all([
49  env.STRIPE_KEY.get(),
50  env.SENDGRID_KEY.get()
51]);
52 
53// ❌ Missing .get()
54const key = env.API_KEY;
55 
56// ❌ Module-level cache
57const CACHED_KEY = await env.API_KEY.get(); // Fails
58 
59// ✅ Request-scope cache
60const key = await env.API_KEY.get(); // OK - reuse within request
61```
62 
63## REST API
64 
65Base: `https://api.cloudflare.com/client/v4`
66 
67### Auth
68 
69```bash
70curl -H "Authorization: Bearer $CF_TOKEN" \
71  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/secrets_store/stores
72```
73 
74### Store Operations
75 
76```bash
77# List
78GET /accounts/{account_id}/secrets_store/stores
79 
80# Create
81POST /accounts/{account_id}/secrets_store/stores
82{"name": "my-store"}
83 
84# Delete
85DELETE /accounts/{account_id}/secrets_store/stores/{store_id}
86```
87 
88### Secret Operations
89 
90```bash
91# List
92GET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
93 
94# Create (single)
95POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
96{
97  "name": "my_secret",
98  "value": "secret_value",
99  "scopes": ["workers"],
100  "comment": "Optional"
101}
102 
103# Create (batch)
104POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
105[
106  {"name": "secret_one", "value": "val1", "scopes": ["workers"]},
107  {"name": "secret_two", "value": "val2", "scopes": ["workers", "ai-gateway"]}
108]
109 
110# Get metadata
111GET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
112 
113# Update
114PATCH /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
115{"value": "new_value", "comment": "Updated"}
116 
117# Delete (single)
118DELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
119 
120# Delete (batch)
121DELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
122{"secret_ids": ["id-1", "id-2"]}
123 
124# Duplicate
125POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}/duplicate
126{"name": "new_name"}
127 
128# Quota
129GET /accounts/{account_id}/secrets_store/quota
130```
131 
132### Responses
133 
134Success:
135```json
136{
137  "success": true,
138  "result": {
139    "id": "secret-id-123",
140    "name": "my_secret",
141    "created": "2025-01-11T12:00:00Z",
142    "scopes": ["workers"]
143  }
144}
145```
146 
147Error:
148```json
149{
150  "success": false,
151  "errors": [{"code": 10000, "message": "Name exists"}]
152}
153```
154 
155## TypeScript Helpers
156 
157Official types available via `@cloudflare/workers-types`:
158 
159```typescript
160import type { SecretsStoreSecret } from "@cloudflare/workers-types";
161 
162interface Env {
163  STRIPE_API_KEY: SecretsStoreSecret;
164  DATABASE_URL: SecretsStoreSecret;
165  WORKER_SECRET: string; // Regular Worker secret (direct access)
166}
167```
168 
169Custom helper type:
170 
171```typescript
172interface SecretsStoreBinding {
173  get(): Promise<string>;
174}
175 
176// Fallback helper
177async function getSecretWithFallback(
178  primary: SecretsStoreBinding,
179  fallback?: SecretsStoreBinding
180): Promise<string> {
181  try {
182    return await primary.get();
183  } catch (error) {
184    if (fallback) return await fallback.get();
185    throw error;
186  }
187}
188 
189// Batch helper
190async function getAllSecrets(
191  secrets: Record<string, SecretsStoreBinding>
192): Promise<Record<string, string>> {
193  const entries = await Promise.all(
194    Object.entries(secrets).map(async ([k, v]) => [k, await v.get()])
195  );
196  return Object.fromEntries(entries);
197}
198```
199 
200See: [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)
201