Authentication

All Kwill API requests must include a valid API key in the Authorization header:

Authorization: Bearer kwill_…

Creating a keyCopy Anchor Link

1. Go to Settings → Developer in your Kwill workspace.
2. Click Create API key and give it a descriptive name (e.g. my-integration-prod).
3. Copy the key immediately — it is shown only once and cannot be retrieved again.

API keys require the admin role and are available to workspaces on the Studio plan or above.

Key propertiesCopy Anchor Link

Keeping keys secureCopy Anchor Link

• Server-side only. Never include a key in frontend JavaScript, mobile apps, or any code that is shipped to end users.
• Environment variables. Store keys as environment variables (e.g. KWILL_API_KEY) and read them at runtime.
• Secret managers. For production, use a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or Doppler.
• Never commit. Add .env* files to .gitignore. Rotate any key that is accidentally committed.

Revoking and rotatingCopy Anchor Link

To revoke a key:

1. Go to Settings → Developer.
2. Find the key by name and click Revoke.

The key is invalidated immediately — any request using it will receive a 401 Unauthorized response.

To rotate, revoke the old key and create a new one, then update all places where the old key was used before the revoke.

Error responsesCopy Anchor Link

An invalid or missing key returns:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

Check that:

• The header name is exactly Authorization (case-insensitive per HTTP, but use this casing for clarity).
• The value starts with Bearer (with a space) followed by your key.
• The key has not been revoked.
• Your workspace is on the Studio plan or above.