Developer Resources
Scopes
The permission grammar for API tokens — modules, actions, wildcards, and what each one gates.
Scopes control what a service-account token can do. The grammar is <action>:<module> — read:customers, write:instances — and every API operation declares the scope it requires. This page lists what each pair gates, verified against the OpenAPI specification; the generated API reference shows the scope each individual operation declares. The specification also publishes the list itself: its bearerAuth security scheme carries x-kaiten-scopes, the 26 read: and write: scopes an organization credential can hold.
Modules
| Module | read: gives | write: gives |
|---|---|---|
customers | List and view customers, their integration links, and external-ID lookups | Create, update, and delete customers; manage their integration links |
instances | List and view instances, read entitlement usage, read the audit trail | Create, update, and delete instances; report entitlement usage; manage instance integration links |
licenses | List and view licenses, License families, and their granted entitlements | Create, update, and delete licenses; publish, archive, and unarchive a version; assign, update, and remove license entitlements |
entitlements | List and view entitlements, groups, and group usage | Create, update, and delete entitlements and groups; manage group membership |
feature_flags | List and view flags, read the targeting context, evaluate via OFREP, read the OpenFeature manifest | Create, update, and delete flags; lint and test targeting rules |
components | List and view components | Create, update, and delete components |
releases | List and view releases | Create and delete releases (releases are immutable — there is no update) |
deployment_zones | List and view deployment zones | Create, update, and delete deployment zones |
metadata_fields | List and view metadata fields | Create, update, reorder, archive, and unarchive fields; run schema-change dry runs |
organizations | List and view connectors, their state, and their settings and settings schema | Activate and deactivate a connector for your organization, and write or clear its settings |
tokens | List service accounts and tokens (metadata only — never secret values) | Create and rename service accounts; issue and revoke tokens |
notifications | Read the caller's own notification feed and preferences | Mark the caller's notifications read; set the caller's preferences |
notifications is narrower than every other module: both scopes reach the caller's own feed, read state, and preferences, and nothing about anyone else's data. A console session needs them for the bell to work — on a self-hosted stack, the identity provider is what puts them in the session's scopes claim.
Wildcards
| Scope | Grants |
|---|---|
read:* | Read access to every module |
write:* | Everything — reads, writes, and deletions, on every module |
delete:* is a valid scope that grants nothing. The grammar accepts a wildcard behind any valid action, so a token can be issued with delete:* — but no implication rule consumes it, so it authorizes no deletion anywhere. A token minted with delete:* in the belief that it can delete everything deletes nothing. Only write:* grants deletions.
Rules
write:<module>impliesread:<module>, and on this API every delete operation requireswrite:<module>— a token withwrite:instancesneeds nothing else to manage instances end to end.write:<module>does not satisfy adelete:<module>requirement; the three that exist are on the Platform API.- The OFREP evaluation endpoints (
/ofrep/v1/...) requireread:feature_flags— that pluswrite:instances(to report usage) is the natural pair for your product's backend. - Scopes are fixed at token creation. To change a token's scopes, issue a new token and revoke the old one.
write:tokensis an administrative scope. The scopes requested for a new token are checked for their format, not against the scopes of the credential that issues it: a holder ofwrite:tokenscan issue a token that carries any scope. Grant it as you would grantwrite:*.
The rest of the grammar
The scope grammar defines more than the table above uses:
- Fifteen modules, three actions — the grammar defines 45 valid pairs. The table above covers every pair this API requires.
- A third action,
delete:, exists and is used by the internal Platform API for its destructive operations. Only threedelete:scopes gate anything at all —delete:organizations,delete:memberships,delete:users, all three on that surface. The other twelve (delete:licenses,delete:webhooks, …) pass validation when a token is issued and open no door: no operation requires them. On the API documented here, delete endpoints requirewrite:<module>. usersandmembershipsappear in the grammar but no operation on this API requires them, and an organization credential can make no use of them: they are the two modulesx-kaiten-scopesleaves out.membershipsexists only fordelete:memberships: removing one person's membership is a narrower, separately grantable privilege than deleting the whole organization or the user account.webhooksgates webhook endpoint management, which is part of Kaiten Cloud —read:webhooksfor listing endpoints and the delivery history,write:webhooksfor creating, updating, and deleting them; see managing endpoints.
No roles, yet
Scopes are the whole authorization model. Kaiten has no first-class notion of a role, so "organization admin" is a token-granting policy rather than something the API enforces: a scope such as write:metadata_fields is administrative by convention, and any token holding it can use it. Design your token issuance accordingly — a role check is planned as defence in depth, not as a replacement for narrow scopes.
Grant the narrowest set that works, and keep what runs inside your product apart from what provisions it. The console's token form offers both as presets over the table above. Data plane is what a backend or an SDK running in your product calls: read:feature_flags, read:customers, read:licenses, read:entitlements, and write:instances — the last one to report usage; a backend that only evaluates flags and reports usage needs the first and the last alone. Control plane is automation that provisions: write: on instances, licenses, customers, deployment zones, releases, components, organizations, and tokens.
Where to go next
Authentication
The three credential families — identity-provider JWTs, ksh_ access tokens, and ksm_ platform credentials — the identity model behind them, and the token lifecycle from issue to revocation.
API Conventions
What every endpoint of the Kaiten API shares — identifiers and slug rules, cursor pagination, the problem+json error envelope, field formats, and bringing your own identifiers.