Authentication

Every request to the Kasar API must include a valid API token. Tokens identify the user, the organization, and the permissions granted to the caller.

API Tokens

API tokens use the ksr_ prefix (the value after the prefix is a signed JWT). Pass the token in the Authorization header as a Bearer token — the header must start with Bearer ksr_:

curl -X GET https://kasar.app/api/v1/records/contacts \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json"

Creating a Token

1. Open Settings in the Kasar sidebar.
2. Navigate to the API section.
3. Click Create token.
4. Give the token a descriptive name (e.g. "Zapier integration", "MCP server").
5. Select the scopes you need.
6. Copy the token immediately — it will not be shown again.

Scopes

Each token is issued with one or more scopes. A token issued without explicit scopes defaults to ["mcp"].

The token's scopes are recorded on the request context and returned by GET /api/v1/me, but the REST API does not gate individual endpoints by scope. What a token can actually read and write is governed entirely by the workspace user's role and the per-object visibility rules (RBAC), exactly as it would be in the app. A token never grants more access than the user it belongs to.

Token Payload

When the API validates a token, it builds a request context with the following information used to determine the organization and permissions:

Admin status is resolved from the workspace user's role (a role flagged as the organization's system/admin role). Admin tokens can perform admin-only operations such as editing the data model, managing lists, importing, exporting, and detecting or merging duplicates. Non-admin admin-only calls are rejected with a PERMISSION_DENIED error.

Example Request

A complete example that fetches the first 10 contacts:

curl -X GET "https://kasar.app/api/v1/records/contacts?limit=10" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json"

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "Alice",
      "last_name": "Martin",
      "email": "alice@example.com",
      "company": "Acme Corp",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 87,
  "nextCursor": "eyJpZCI6IjU1MGU4NDAw..."
}

Error Responses

Missing or Invalid Token

If the Authorization header is absent, does not start with Bearer ksr_, or carries a token that is malformed, revoked, or expired, the API returns 401 with a single combined error:

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API token. Use a Bearer ksr_* token."
}

Insufficient Permissions

The token is valid, but the workspace user lacks the role or visibility needed for the operation (e.g. an admin-only call made with a non-admin token, or replying to a thread the user does not own). These are returned with a PERMISSION_DENIED code and an HTTP 400 status. The body follows the standard error shape (no boolean error field):

{
  "code": "PERMISSION_DENIED",
  "message": "Data-model changes require an organization admin token."
}

Internal Error

If an unexpected error occurs while handling the request, the API returns 500:

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR",
  "message": "..."
}

Security Best Practices

• Never expose tokens in client-side code. Tokens must only be used in server-side applications, backend services, or automation tools. Never embed them in JavaScript that runs in the browser.

• Use environment variables. Store tokens in environment variables (KASAR_API_TOKEN) rather than hardcoding them in source files.

  export KASAR_API_TOKEN="ksr_a1b2c3d4e5f6..."

  const token = process.env.KASAR_API_TOKEN;

• Rotate tokens regularly. Create new tokens and revoke old ones on a regular schedule, especially when team members leave or integrations are decommissioned.

• Issue tokens for least-privileged users. A token never grants more than the workspace user it belongs to. Create the token under a user whose role only has the access the integration needs, rather than under an admin, to limit the blast radius if a token is compromised.

• Revoke compromised tokens immediately. If you suspect a token has been exposed, go to Settings > API and revoke it. Create a new one for your integration.

• Audit token usage. Review which tokens exist and when they were last used. Remove tokens that are no longer needed.