Overview & Authentication

import { Aside } from ‘@astrojs/starlight/components’;

The Kotauth REST API v1 is a machine-to-machine interface for managing workspace resources programmatically. It covers the full lifecycle of users, roles, groups, applications, sessions, and audit logs.

Base URL:

{baseUrl}/t/{workspaceSlug}/api/v1

For example: https://auth.yourdomain.com/t/my-app/api/v1

An interactive Swagger UI is also available on any running instance at:

/t/{workspaceSlug}/api/v1/docs

Authentication

All API endpoints require an API key passed as a Bearer token:

Authorization: Bearer kauth_my-app_abcdef1234567890

API keys are created and managed in the admin console under Settings → API Keys for each workspace. The key format is kauth_<workspaceSlug>_<random> — the prefix makes them easy to identify in logs and secret scanners.

Scopes

Each API key carries a set of scopes that restrict which operations it may perform. Attempting an operation without the required scope returns 403 Forbidden.

Scope	Grants access to
`users:read`	List and retrieve users
`users:write`	Create, update, disable users; assign and remove roles
`roles:read`	List and retrieve roles
`roles:write`	Create, update, delete roles
`groups:read`	List and retrieve groups
`groups:write`	Create, update, delete groups; manage members
`applications:read`	List and retrieve applications
`applications:write`	Update and disable applications
`sessions:read`	List active sessions
`sessions:write`	Revoke sessions
`audit_logs:read`	Read audit log events

Always issue API keys with the minimum scope required. A key used for read-only reporting should not have write scopes.

Pagination

List endpoints return paginated results with a meta object:

{
  "data": [...],
  "meta": {
    "total": 143,
    "offset": 0,
    "limit": 20
  }
}

Use offset and limit query parameters to paginate:

GET /users?offset=20&limit=20

Error format

All errors follow RFC 7807 Problem Details with Content-Type: application/problem+json:

{
  "type": "https://kotauth.dev/errors/422",
  "title": "Validation Error",
  "status": 422,
  "detail": "Username may only contain letters, digits, dots, underscores, and hyphens."
}

Common error codes

Status	Meaning
`400`	Bad request — malformed JSON or missing required fields
`401`	Missing or invalid API key
`403`	Valid key but insufficient scope
`404`	Resource not found
`409`	Conflict — resource already exists (e.g. duplicate username)
`422`	Validation error — request is well-formed but semantically invalid
`429`	Rate limit exceeded
`500`	Internal server error