Skip to main content

Authentication

The TakeTheme API authenticates requests with API keys. Every request must carry your key in one of two ways:

tt-api-key: tt_YOUR_API_KEY

or as a standard Bearer token:

Authorization: Bearer tt_YOUR_API_KEY

Both are equivalent; tt-api-key is preferred because it can't collide with other authorization schemes.

Key format

Keys look like tt_ followed by a 64-character hex string. If your key doesn't start with tt_, the API rejects it with INVALID_API_KEY_FORMAT before any lookup happens.

Making Authenticated Requests​

cURL​

curl -X GET "https://api.taketheme.com/api/v1/product" \
  -H "tt-api-key: $TAKETHEME_API_KEY" \
  -H "Content-Type: application/json"

JavaScript (Axios)​

import axios from "axios";

const client = axios.create({
  baseURL: "https://api.taketheme.com/api/v1",
  headers: {
    "tt-api-key": process.env.TAKETHEME_API_KEY,
    "Content-Type": "application/json",
  },
});

const response = await client.get("/product");
const data = response.data;

Python​

import requests
import os

headers = {
    'tt-api-key': os.environ.get('TAKETHEME_API_KEY'),
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.taketheme.com/api/v1/product',
    headers=headers
)

data = response.json()

.NET​

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.BaseAddress = new Uri("https://api.taketheme.com/api/v1/");
client.DefaultRequestHeaders.Add("tt-api-key", Environment.GetEnvironmentVariable("TAKETHEME_API_KEY"));

var response = await client.GetAsync("product");
var data = await response.Content.ReadAsStringAsync();

Scopes​

Every API key carries a list of scopes — pairs of a resource and the actions allowed on it:

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

Actions map to HTTP semantics: READ (GET), WRITE (POST), UPDATE (PATCH/PUT), DELETE (DELETE). An endpoint declares exactly one required (resource, action) pair; if your key doesn't have it, the request fails with 403 INSUFFICIENT_SCOPE.

See the full scopes reference for the resource list and which scope each endpoint requires.

Least privilege

Grant only the scopes an integration needs. A fulfillment sync needs ORDERS:READ + ORDERS:UPDATE — not PRODUCTS:DELETE.

Environments​

Each key is created for one environment: production, staging, or development. Use separate keys per environment so a leaked development key never touches production data.

IP Allowlisting​

You can restrict a key to specific IP addresses. When an allowlist is set, requests from any other address are rejected with 403 IP_NOT_WHITELISTED.

  1. Go to Dashboard → Settings → API Keys
  2. Open the key you want to restrict
  3. Add allowed IP addresses (exact match) or CIDR-style ranges
  4. Save

Authentication Errors​

Errors use the standard envelope — see Error Handling:

{
  "status": 401,
  "message": "API key not found or has been revoked"
}
StatusCodeMeaning
401API_KEY_REQUIREDNo key in tt-api-key or Authorization header
401INVALID_API_KEY_FORMATKey doesn't start with tt_ or is too short
401INVALID_API_KEYKey not found, or hash verification failed
401API_KEY_REVOKEDKey was revoked (and any grace period has passed)
401API_KEY_INACTIVEKey was deactivated
401API_KEY_EXPIREDKey is past its expiresAt date
401API_KEY_GRACE_PERIOD_EXPIREDRotated/revoked key used after its grace window closed
402STORE_SUSPENDEDThe store this key belongs to is suspended
403INSUFFICIENT_SCOPEKey lacks the (resource, action) scope this endpoint requires
403IP_NOT_WHITELISTEDRequest came from an IP outside the key's allowlist
429API_KEY_USAGE_LIMIT_REACHEDThe key's total usage quota is exhausted

Security Best Practices​

  • Never expose API keys in client-side code, public repositories, or version control
  • Use environment variables to store keys in your applications
  • Rotate keys periodically — rotation issues a new secret while the old one keeps working for a short grace period, so you can switch over without downtime
# .env file
TAKETHEME_API_KEY=tt_abc123...

Next Steps​