Authentication

Create an API key, scope it to the resources you need, and send it as a bearer token.

The Clakta API authenticates with an API key, sent as a bearer token on every request. There are no unauthenticated endpoints.

Create an API key

Open Settings → API keys in your team.
Click Create API key and give it a name that says where it will be used (for example shopify-production).
Select the scopes it needs.
Copy the key immediately — it is shown once and stored only as a hash, so it cannot be retrieved later.

An API key carries your team's access. Keep it on your server, in an environment variable or secret manager. Never ship it in a browser bundle, mobile app, or public repository — anything that reaches a shopper's device is public.

Authenticate a request

Send the key in the Authorization header, prefixed with Bearer :

curl https://api.clakta.com/v1/orders \
  -X POST \
  -H "Authorization: Bearer $CLAKTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_xxxxxxxx",
    "orderId": "1042",
    "platform": "shopify",
    "paymentMethod": "credit_card",
    "status": "pending",
    "totalPrice": 10.4,
    "products": [
      { "id": "sku-1", "name": "Blue shirt", "quantity": 1, "price": 10.4 }
    ],
    "customer": { "name": "John Doe", "email": "john@example.com", "ip": "203.0.113.42" },
    "tracking": { "clkt": null, "utm_source": null, "utm_medium": null, "utm_campaign": null, "utm_content": null }
  }'

Omitting the prefix is the most common mistake and returns 400 bad_request — the header value must be Bearer <key>, not the bare key.

Scopes

A key only reaches what its scopes allow, and each endpoint in this reference states the permission it requires. Scopes are named <resource>.<access>:

Scope	Grants
`orders.read`	Read orders
`orders.write`	Create, update and delete orders
`products.read` / `products.write`	Read / manage products
`customers.read` / `customers.write`	Read / manage customers
`projects.read` / `projects.write`	Read / manage projects
`teams.read` / `teams.write`	Read / manage teams
`analytics.read`	Read analytics and events
`dashboard.read` / `dashboard.write`	Read / manage dashboards
`adsManager.read` / `adsManager.write`	Read / manage connected ad accounts

A write scope implies its matching read scope. Grant the narrowest set that does the job: a storefront integration that only records orders needs orders.write and nothing else.

Two failure modes are worth distinguishing:

401 unauthorized — the key is missing, malformed, or revoked.
403 forbidden — the key is valid but lacks the scope for this endpoint.

Rotating and revoking

Keys can be revoked at any time from Settings → API keys; a revoked key stops working immediately. To rotate without downtime, create the replacement first, deploy it, then revoke the old key.

Requests made with your keys are recorded in Settings → API logs, which is the fastest way to confirm a rotation landed or to find what a failing integration actually sent.