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. Pass the token in the Authorization header as a Bearer token:

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 that control what it can access.

A token with no valid scope will be rejected with a 403 error on every request.

Token Payload

When the API validates a token, it extracts the following information to determine context and permissions:

Admin status is determined from the role column in the workspace_users table. Admin users can access organization-level settings and manage other users through the API.

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 Token

If the Authorization header is absent, the API returns 401:

{
  "error": true,
  "code": "UNAUTHORIZED",
  "message": "Missing or invalid Authorization header"
}

Invalid or Expired Token

If the token is malformed, revoked, or expired:

{
  "error": true,
  "code": "UNAUTHORIZED",
  "message": "Invalid API token"
}

Insufficient Scope

If the token does not have the required scope for the endpoint:

{
  "error": true,
  "code": "PERMISSION_DENIED",
  "message": "Token does not have the required scope for this resource"
}

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.

• Use the minimum required scope. If your integration only needs to read email content, request inbox:content instead of mcp. This limits 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.