API Tokens

API tokens 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 > API Tokens

---

Creating a Token

1. Go to Settings > API Tokens
2. Click "Create Token"
3. Fill in the details:
   • Username — a name to identify this token (lowercase letters, numbers, and hyphens only; 3–50 characters)
   • Description — what this token is used for
4. Choose a Permission Mode (see below)

Permission Modes

Mode	Description
Role	Pick one of the built-in roles: Super Admin, Admin, Marketer, Service Agent, or Analyst
Custom	Granular per-feature permission matrix — select exactly which features and actions to allow

Credentials

After creation, a Token Created dialog shows:

• Client ID — in the form svc-<tenant>-<username>
• Client Secret — shown once only
• A ready-made usage example: a client_credentials curl for the token endpoint you can copy as-is

warning

Save the client secret now — it won't be shown again. If lost, you must regenerate it.

---

Managing Tokens

Action	Description
Edit Permissions	Change the permission mode, role, or custom scopes, and manage Linked Customers. The username is not editable.
Regenerate Secret	Generate a new client_secret (invalidates the old one)
Activate / Deactivate	Temporarily disable the token without deleting it
Delete	Permanently remove the token

---

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

The API Documentation card on this page links to the interactive (Swagger) docs for the Gateway, Marketing, Products, and KB Website APIs. Use these docs to explore available endpoints and request/response formats.

tip

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

---

Webhooks

Webhooks are configured on this same page — the webhook card sits below the tokens list. Use them to receive real-time event notifications on your server.

Combined with System Events — which your backend fires into Orki using these tokens — this page is the hub for two-way integration with your systems.

---

Next Steps

• Webhooks — Receive real-time notifications when events happen in Orki
• System Events — Fire structured events at a chat using these tokens
• Team Management — Manage team members and roles