Authentication

Every request is authenticated with a project-scoped API key. The project is derived from the key, so a request can never touch another project data.

Key format

Keys look like cfy_<live|test>_<40 chars>. Production keys are prefixed cfy_live_ and sandbox keys cfy_test_. Create and revoke keys in the CraftifyAI web app under Settings, then Developer API (available to project owners and managers).

A key is shown only once at creation and stored hashed at rest. Copy it immediately and keep it secret. If a key is lost or leaked, revoke it and create a new one. Never embed a key in client-side code or commit it to a repository.

Sending the key

Send the key as a Bearer token in the Authorization header. This is the preferred form.

bash

curl https://api.craftify.ai/v1/ping \
  -H "Authorization: Bearer cfy_live_xxx"

For tools that cannot set Authorization, the X-API-Key header is accepted as an alias.

bash

curl https://api.craftify.ai/v1/ping \
  -H "X-API-Key: cfy_live_xxx"

Scopes

Each key carries a set of scopes. An endpoint returns 403 if the key is missing the scope it needs. Follow least privilege and grant a key only the scopes its integration actually uses.

Scope	Grants
`contacts:read`	Read contacts, interaction logs, and reference data.
`contacts:write`	Create and update contacts.
`interactions:write`	Add interaction logs.
`webhooks:manage`	Manage webhook subscriptions.

Key rotation

Rotate keys without downtime by overlapping the old and new key:

Create a new key with the same scopes.
Deploy the new key to your integration and confirm traffic flows.
Revoke the old key once nothing is using it.

Because keys are independent, you can run both during the migration window and revoke the old one only after the switch is verified.

Authentication errors

Auth failures use the standard error envelope. Two codes are specific to authentication:

401 — the key is missing, malformed, unknown, revoked, or expired. The message is intentionally opaque and does not reveal whether a key exists.
403 — the key is valid but lacks the scope the endpoint requires.

See Rate limits & errors for the full status code table and the error envelope shape.