Authentication & API keys

API keys

Send the key as a Bearer token on every request:

Authorization: Bearer sk_live_…

• Format: sk_live_ followed by 43 characters. Anything else answers 401 without even reaching our database.
• Every key is live: there is no test mode. Tag test leads (for example docs-test) so you can find and remove them.
• The key is shown once, when it is created. We store only a keyed hash of it, so nobody — including SpaceKru — can show it to you again.
• Up to 5 active keys per account. Name each key after the tool that uses it ("Zapier", "Website form", "ERP sync") so you can revoke one without touching the rest.

Who can create keys

Only the account owner, in Integrations → API & Webhooks (key names up to 100 characters). The same panel shows each key's last use, the request count of the last 30 days, and every webhook subscription.

Scopes

• Read only (read): every GET except webhooks and conversations.
• Read & write (read + write): everything that creates or changes data, and every /subscriptions operation.
• AI conversations (conversations, optional, only with read & write): the /conversations operations. They spend AI tokens, so the owner grants it explicitly when creating the key.

A key without the scope an operation needs answers 403 INSUFFICIENT_SCOPE.

Plan modules (403)

Some operations need a module of your plan, the same one the app needs: crm (leads, deals, campaigns), sales_os (products, quotes, orders) and scheduler (bookings). Without it the answer is 403 MODULE_NOT_AVAILABLE. Every paid plan includes the three modules today.

Response language

error.message comes in English or Spanish. Send Accept-Language: es (or en) to choose; without it, the language of the profile of the person who created the key is used. The Content-Language header tells you which one you got. Error codes, field names, event names and details[].issue never change: branch on them, not on the message.

Plan requirements (402)

The API works only while the account is on an active paid plan (the 7-day free trial of a paid plan counts). Otherwise every request answers 402 PLAN_UPGRADE_REQUIRED with one of these messages:

• There is no grace period: a payment that fails pauses the API right away (within about a minute).
• Keys are not deleted. When the account is back on a paid plan, the same keys and webhooks work again.
• If we can't verify the plan for a moment, you get 503 ELIGIBILITY_UNAVAILABLE with Retry-After: 10. It fails closed: retry, it is never a free pass.

401 vs 402 vs 403

Revoke and rotate keys

• Revoke a key in Integrations → API & Webhooks. It stops working on the very next request — there is no cache.
• Revoking a key also deactivates the webhook subscriptions it created (disabled_reason: "key_revoked"). Subscriptions created by other keys are not affected.

To rotate a key without downtime:

1. Create a new key with the same access.
2. Deploy it to your integration (environment variable, Zapier/Make/n8n connection).
3. Check in the panel that the new key shows a recent "Last used".
4. Revoke the old key. If the old key created webhooks, subscribe them again with the new key (and if they used exclude_own_changes, they now skip the new key's changes).

Security & best practices

• Server-to-server only. The API sends no CORS headers, so browsers block calls from web pages — on purpose. A key in front-end code, a mobile app or a public repository can be stolen; keep it on a server or inside your automation tool.
• Store keys as secrets: environment variables, a secrets manager, or the credential store of Zapier, Make or n8n.
• Least privilege: a Read only key for reporting; AI conversations only for the key of your chat integration.
• One key per integration, so revoking one never breaks the others.
• Verify every webhook signature and reject old timestamps — see Verify signatures.
• Tenant isolation: a key can only ever see its own account. An id from another account answers 404, exactly like an id that does not exist — also inside a body (lead_id, product_id…).
• Webhook targets are restricted to public https:// hosts on port 443, checked on every delivery; redirects are never followed.

Example: check a key

curl "https://app.spacekru.com/api/public/v1/ping" \
  -H "Authorization: Bearer $SPACEKRU_API_KEY"

const res = await fetch('https://app.spacekru.com/api/public/v1/ping', {
  headers: {
    Authorization: `Bearer ${process.env.SPACEKRU_API_KEY}`,
  },
});
const body = await res.json();
if (!res.ok) {
  // Branch on body.error.code; quote body.error.request_id to support.
  throw new Error(`${body.error.code}: ${body.error.message} (request ${body.error.request_id})`);
}
console.log(body);

import os

import requests

r = requests.get(
    "https://app.spacekru.com/api/public/v1/ping",
    headers={
        "Authorization": f"Bearer {os.environ['SPACEKRU_API_KEY']}",
    },
    timeout=30,
)
body = r.json()
if not r.ok:
    # Branch on body["error"]["code"]; quote body["error"]["request_id"] to support.
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']} (request {body['error']['request_id']})")
print(body)