Service Account Tokens

Service accounts provide programmatic API access to Orki. They let external systems interact with your tenant without requiring a human user — perfect for integrations, automations, and custom workflows.

Path: Settings > Service Account Tokens

---

Creating a Service Account

1. Go to Settings > Service Account Tokens
2. Click "Create Service Account"
3. Fill in the details:
   • Username — a name to identify this service account
   • Description — what this service account is used for
4. Select a permission mode (see below)

Permission Modes

Mode	Description
Admin	Full access to all features
Agent	Can handle conversations and use AI features
Custom	Granular per-feature permissions — select exactly which features to allow

Credentials

After creation, you receive a client_id and client_secret.

warning

Store the client_secret securely — it is only shown once. If lost, you must regenerate it.

---

Managing Service Accounts

Action	Description
Edit	Update the username and description
Regenerate Secret	Generate a new client_secret (invalidates the old one)
Activate / Deactivate	Temporarily disable the account without deleting it
Delete	Permanently remove the service account

---

Using the Token

Authenticate via Keycloak token exchange using the client_credentials grant type:

curl -X POST "https://auth.orki.ai/realms/orki/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

The response includes an access_token. Use it in the Authorization header for all API calls:

curl -X GET "https://api.orki.ai/gateway/api/v1/tenants/{tenantId}/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

API Documentation

Each service exposes Swagger documentation at its /swagger endpoint. Use these docs to explore available endpoints and request/response formats.

tip

Create separate service accounts for different integrations so you can revoke access independently without affecting other systems.

---

Next Steps

• Webhooks — Receive real-time notifications when events happen in Orki
• Security — Manage your account security settings
• Team Management — Manage team members and roles