Skip to main content

API Keys

API keys authenticate your applications with the TakeTheme API. This guide covers how to create, manage, and secure your keys.

Plan availability

API access is available on Pro and Scale plans. On other plans the API Keys section is not available in the dashboard and key-authenticated requests are rejected.

Creating API Keys​

Via Dashboard​

  1. Log in to your TakeTheme Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New Key
  4. Configure the key:
    • Name: A descriptive name (e.g., "Production Backend", "Inventory Sync")
    • Environment: production, staging, or development
    • Scopes: The resource + action pairs the key may use (see scopes reference)
    • IP allowlist (optional): Restrict usage to specific IPs
    • Expiry / usage limit (optional): Auto-expire the key at a date, or cap its total number of requests
  5. Click Create Key
  6. Copy your key immediately — it won't be shown again
Important

The secret is displayed only once, at creation. Only a hash is stored server-side; if you lose the key, rotate it or create a new one.

Key Structure​

tt_{64_character_hex_string}
ComponentDescriptionLength
tt_TakeTheme prefix3
{64_character_hex_string}Cryptographic random hex string64

Example:

tt_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

For display, only the last 4 characters are ever shown after creation.

Managing Keys​

Viewing Keys​

In the dashboard you can see each key's name, environment, creation date, last-used timestamp, total usage count, scopes, and IP restrictions — never the secret itself.

Rotating Keys​

Rotation issues a new secret for the same key while the old secret keeps working for a short grace period, so you can switch your application over with zero downtime:

  1. Rotate the key (dashboard or POST /api-key/{keyId}/rotate)
  2. Update your application to the new secret
  3. The old secret stops working when the grace period ends (API_KEY_GRACE_PERIOD_EXPIRED)

Revoking Keys​

Revoking disables a key (POST /api-key/{keyId}/revoke); deleting removes it entirely (DELETE /api-key/{keyId}). Applications using a revoked key receive 401 API_KEY_REVOKED.

danger

Revocation takes effect immediately (subject to any grace period configured at revoke time). Make sure nothing critical still uses the key.

Scopes & Permissions​

A key's scopes are an array of resource + actions pairs:

{
  "scopes": [
    { "resource": "PRODUCTS", "actions": ["READ", "WRITE", "UPDATE"] },
    { "resource": "ORDERS", "actions": ["READ"] }
  ]
}

Available actions are READ, WRITE (create), UPDATE, and DELETE. Available resources:

ANALYTICS, BILLING, BLOGS, CATEGORIES, COUPONS, CUSTOMERS, DISCOUNTS, DOMAINS, INTEGRATION, MARKETING, ORDERS, PRODUCTS, REVIEWS, SECRETS, SEGMENTS, STAFF, STORE_SETTINGS, SUPPORT, THEME, UPSELLS, API_KEYS

See the scopes reference for which scope each endpoint requires.

Best Practices​

Use Descriptive Names​

✓ "Production Web Server"
✓ "Staging Environment"
✓ "Inventory Sync Service"

✗ "Key 1"
✗ "Test"

Implement Least Privilege​

Only grant the scopes an integration needs:

// ✓ Good: an inventory sync needs products only
{ "scopes": [{ "resource": "PRODUCTS", "actions": ["READ", "UPDATE"] }] }

// ✗ Bad: granting every resource with every action "just in case"

Separate Keys by Environment​

EnvironmentUsage
developmentLocal development and testing
stagingPre-production environment
productionLive production with customer data

Store Keys Securely​

# ✓ Good: environment variable
export TAKETHEME_API_KEY=tt_xxx

# ✗ Bad: hardcoded in source code

Monitor Key Usage​

Each key tracks lastUsedAt and a total usage count, aggregated daily. Review them via the dashboard or GET /api-key/stats, and watch for keys that are unused (candidates for revocation) or unexpectedly busy.

Programmatic Key Management​

Keys can manage keys — the endpoints require the API_KEYS scope. Note the singular /api-key prefix:

MethodPathRequired action
GET/api-keyREAD
GET/api-key/statsREAD
GET/api-key/{keyId}READ
POST/api-keyWRITE
PATCH/api-key/{keyId}UPDATE
POST/api-key/{keyId}/revokeUPDATE
POST/api-key/{keyId}/rotateWRITE
DELETE/api-key/{keyId}DELETE

Create a Key​

curl -X POST "https://api.taketheme.com/api/v1/api-key" \
  -H "tt-api-key: tt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keyName": "New Integration Key",
    "environment": "production",
    "scopes": [
      { "resource": "PRODUCTS", "actions": ["READ"] },
      { "resource": "ORDERS", "actions": ["READ"] }
    ]
  }'

List Keys​

curl -X GET "https://api.taketheme.com/api/v1/api-key" \
  -H "tt-api-key: tt_xxx"

Revoke a Key​

curl -X POST "https://api.taketheme.com/api/v1/api-key/{keyId}/revoke" \
  -H "tt-api-key: tt_xxx"