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 API keys.

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", "Mobile App")
    • Environment: Live or Test
    • Scopes: Select the required permissions
    • IP Restrictions: Optionally limit to specific IPs
  5. Click Create Key
  6. Copy your key immediately — it won't be shown again
Important

Your secret API key is displayed only once when created. Store it securely. If you lose it, you'll need to generate a new key.

Key Structure​

TakeTheme API keys follow this format:

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

Example:

tt_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

The key is generated using crypto.randomBytes(32) which produces a 64-character hexadecimal string, ensuring cryptographic security.

Managing Keys​

Viewing Keys​

In your dashboard, you can view:

  • Key name and creation date
  • Last used timestamp
  • Assigned scopes
  • IP restrictions (if any)
note

For security, only the first and last 4 characters of each key are displayed. The full key is never shown after initial creation.

Rotating Keys​

Regular key rotation is a security best practice:

  1. Create a new API key with the same permissions
  2. Update your application to use the new key
  3. Monitor for any issues
  4. Revoke the old key once confirmed working

Revoking Keys​

To immediately disable an API key:

  1. Go to Settings → API Keys
  2. Find the key to revoke
  3. Click the ⋮ menu → Revoke
  4. Confirm the action
danger

Revoking a key is permanent. Any applications using that key will immediately lose access.

Scopes & Permissions​

Configure fine-grained access control with scopes:

Category Scopes​

ScopePermissions
read:categoriesList, retrieve category details
write:categoriesCreate, update, delete categories

Product Scopes​

ScopePermissions
read:productsList, retrieve product details
write:productsCreate, update, delete products

Order Scopes​

ScopePermissions
read:ordersList, retrieve order details
write:ordersCreate, update, cancel orders, update fulfillment, and refunds

Customer Scopes​

ScopePermissions
read:customersList, retrieve customer profiles
write:customersCreate, update customer data

Staff Scopes​

ScopePermissions
read:staffList, retrieve staff members
write:staffCreate, update, delete staff

Store Scopes​

ScopePermissions
read:storeView store settings and configuration
write:storeUpdate store settings, countries, and marketing configuration

Best Practices​

Use Descriptive Names​

Name keys based on their purpose:

✓ "Production Web Server"
✓ "Staging Environment"
✓ "Mobile iOS App"
✓ "Inventory Sync Service"

✗ "Key 1"
✗ "Test"
✗ "asdf"

Implement Least Privilege​

Only request the scopes your application needs:

// ✓ Good: Only request what you need
const key = await createApiKey({
  name: "Inventory Sync",
  scopes: ["read:products", "write:inventory"],
});

// ✗ Bad: Requesting unnecessary broad access
const key = await createApiKey({
  name: "Inventory Sync",
  scopes: ["*"], // Never do this
});

Separate Keys by Environment​

Use different keys for each 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
const apiKey = "tt_xxx"; // Never do this

Monitor Key Usage​

Regularly review:

  • Which keys are actively used
  • Last activity timestamps
  • Any unusual access patterns
  • Failed authentication attempts

Programmatic Key Management​

You can manage API keys via the API itself (requires write:api_keys scope):

Create a Key​

curl -X POST "https://api.taketheme.com/api/v1/api-keys" \
  -H "tt-api-key: tt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Integration Key",
    "scopes": ["read:products", "read:orders"]
  }'

List Keys​

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

Revoke a Key​

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