Skip to main content
Service accounts authenticate using client credentials (client ID + secret) and act on behalf of the organization rather than a specific user. Use them for CI/CD pipelines, backend automation, and monitoring scripts.

​
Endpoints

MethodPathPurpose
POST/service-accountsCreate service account
GET/service-accountsList service accounts
GET/service-accounts/:idGet service account
POST/service-accounts/:id/rotate-secretRotate secret
DELETE/service-accounts/:idDelete service account
id path params are service account UUIDs (not the OAuth clientId).

​
Create service account

curl -X POST https://api.kontext.dev/api/v1/service-accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline",
    "description": "Used by GitHub Actions to manage integrations"
  }'

​
Request body

FieldTypeRequiredDescription
namestringYesDisplay name
descriptionstringNoHuman-readable description

​
Response

The response includes a credentials object with clientId and clientSecret. The secret is only returned on create and rotate — store it immediately. Response shape: { "serviceAccount": { ... }, "credentials": { ... } } Use these credentials with the Management SDK: 
import { KontextManagementClient } from "@kontext-dev/js-sdk/management";

const client = new KontextManagementClient({
  baseUrl: "https://api.kontext.dev",
  credentials: {
    clientId: "sa_your-service-account-id",
    clientSecret: "your-service-account-secret",
  },
});
Or request a token directly: 
curl -X POST https://api.kontext.dev/oauth2/token \
  -u "sa_client-id:client-secret" \
  -d "grant_type=client_credentials" \
  -d "scope=management:all"

​
List service accounts

curl https://api.kontext.dev/api/v1/service-accounts \
  -H "Authorization: Bearer $TOKEN"
Returns all service accounts in the organization. Credentials are never included in list responses.

​
Get service account

curl https://api.kontext.dev/api/v1/service-accounts/33333333-3333-4333-8333-333333333333 \
  -H "Authorization: Bearer $TOKEN"
Returns metadata for the service account. Does not include credentials.

​
Rotate secret

curl -X POST https://api.kontext.dev/api/v1/service-accounts/33333333-3333-4333-8333-333333333333/rotate-secret \
  -H "Authorization: Bearer $TOKEN"
Generates a new clientSecret and invalidates the previous one immediately. Any active tokens issued with the old secret continue to work until they expire, but no new tokens can be obtained with the old secret. Store the new secret — it will not be shown again.

​
Delete service account

curl -X DELETE https://api.kontext.dev/api/v1/service-accounts/33333333-3333-4333-8333-333333333333 \
  -H "Authorization: Bearer $TOKEN"
Permanently deletes the service account and revokes all tokens associated with it. This action cannot be undone.