Skip to main content
Every API request requires an API key in the Authorization header.

​
Authenticating requests

Pass your API key as a Bearer token: 
curl https://gateway.takumo.io/v1/tokenize \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "const key = \"AKIAIOSFODNN7EXAMPLE\"", "filename": "config.ts"}'
In code: 
const response = await fetch("https://gateway.takumo.io/v1/tokenize", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TAKUMO_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: sourceCode,
    filename: "config.ts"
  })
});

​
How keys are validated

  1. The gateway receives your key from the Authorization header.
  2. It computes a SHA-256 hash of the raw key.
  3. The hash is looked up in the database.
  4. If found and not revoked, the request proceeds.
  5. Constant-time comparison prevents timing attacks.
The raw key is never stored. It exists only at creation time. After you close the creation dialog in the dashboard, the only copy is the one you saved.

​
Key prefixes

PrefixEnvironment
tk_live_Production
tk_test_Test / development
Keys are 64-character hex strings following the prefix.

​
Key scopes

Each key has a set of scopes that control what it can do. A request that requires a scope the key doesn’t have returns 403 FORBIDDEN.
ScopeWhat it controls
shield:readRead scan results and detection history
shield:writeRun scans, tokenize, and rehydrate
audit:readRead audit log entries
fleet:readView gateway fleet status
fleet:writeRegister and manage gateways
policy:readRead policy configurations
policy:writeCreate and update policies
org:readRead organization settings
org:writeUpdate organization settings, manage members
Assign the minimum scopes needed. A key used only for secret scanning needs shield:write and nothing else.

​
Rate limit headers

Every response includes rate limit headers, regardless of whether the request succeeded:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait before retrying (only present on 429 responses)
Example response headers: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1710360000
When you receive a 429 Too Many Requests, stop and wait for the number of seconds specified in Retry-After. See Rate Limits for per-plan limits.

​
Key rotation

For zero-downtime rotation:
  1. Create a new key with the same scopes.
  2. Deploy the new key to your tools.
  3. Verify requests succeed with the new key.
  4. Revoke the old key.
Revocation takes effect within seconds. A revoked key returns 401 UNAUTHORIZED immediately. There is no undo.

​
Error responses

StatusCodeWhen
401UNAUTHORIZEDMissing key, invalid key, expired key, revoked key
403FORBIDDENKey lacks required scope, feature not available on your plan
429RATE_LIMITEDToo many requests in the current window
See Errors for the full error response format.