Connect Your Application
Create a service account, generate an API token, and make your first authenticated API call.
Connect Your Application
To interact with Kaiten programmatically (from your backend, CI/CD, or scripts), you need a Service Account and an API Token (ksh_*).
Create a Service Account
Navigate to Integrations → Service Accounts in the dashboard, then click New Service Account.
Give it a descriptive name (e.g. my-app-backend).
A Service Account is a machine user — it has no email and belongs to your organization. It can hold multiple API tokens with different scopes.
Generate an API Token
- Click on your service account
- Click Generate Token
- Give it a name (e.g.
production) - Select Scopes:
read:customers— list and view customersread:instances— list and view instancesread:feature_flags— evaluate feature flagswrite:customers— create/update customers- Or use
read:*/write:*for full access
- Click Create
Copy the token immediately — it is shown only once. It looks like: ksh_abcdef123456...
Make Your First API Call
curl http://localhost:6000/api/customers \
-H "Authorization: Bearer ksh_your_token_here"Response:
{
"items": [
{
"id": "uuid-...",
"name": "Sakura Tokyo",
"slug": "sakura-tokyo"
}
],
"total": 3
}How Authentication Works
When you send a request with a ksh_* token, here's what happens:
Your App Traefik Gateway Go API
| | |
|-- Bearer ksh_xxx ---------->| |
| |-- ForwardAuth -------->|
| | /api/tokens/validate |
| |<-- unsigned JWT -------|
| | |
| |-- JWT + request ------>|
| | |-- extract Principal
| | | (UserID, OrgID, Scopes)
|<-- API response ------------|<-- response ------------|- Traefik detects the
ksh_*pattern in theAuthorizationheader - It forwards the request to
/api/tokens/validatevia ForwardAuth - The API validates the token hash, checks expiry, and generates an unsigned JWT with the same claims
- The JWT is forwarded to the API handler, which extracts the Principal (user ID, org ID, scopes)
- All database queries are automatically scoped to the organization
Scopes Reference
Scopes follow the pattern <action>:<module>:
| Scope | Access |
|---|---|
read:customers | List/view customers |
write:customers | Create/update/delete customers |
read:instances | List/view instances |
read:feature_flags | Evaluate feature flags |
read:* | Read access to all modules |
write:* | Full access (implies read) |
See the complete scopes reference for all 11 modules.