Service tokens

2 min read

Service tokens let a program authenticate with Kujira without using a person's account. Use them for your own integration, CI/CD pipeline, internal automation, or an external agent working with the API.

Every token belongs to one organization and its actions are identified as performed by that service in the activity log.

Create a token

When creating a token, give it a name that identifies its purpose—such as ci-deployment or crm-integration—and select only the permissions it needs. The complete value begins with kjtk_live_.

Copy the secret immediately

The secret is shown only once. Kujira keeps only a protected version to validate it, so it cannot be recovered later. If you lose it or suspect exposure, create another and revoke the previous one.

Design for minimum access

A token does not inherit the role of whoever uses it: it acts only with the permissions you grant. You also cannot create a token with broader permissions than your own.

Specific permissions

Grant only required actions, such as viewing agents or sending input to a specific agent.

Expiry

Set an expiration date for temporary access. Without one, the token remains active until you revoke it.

IP addresses

When the service operates from known addresses, limit the token to those IPs to prevent use from elsewhere.

One token per integration

Do not share one token across several systems. One token per integration, with its own name and permissions, makes it easier to review, rotate, or revoke without interrupting other services.

Review, rotate, and revoke

The list shows every token's name, permissions, expiry, and last-use time. Periodically review access that is no longer used.

You cannot change an existing token's secret. To rotate it, create a new token, update the service using it, then revoke the old one once you confirm the change works. Revocation is immediate.

Use one with an external agent

You can give a limited token to a coding agent so it can operate Kujira through the API. The connection instructions in this documentation let it load the contract and authentication flow; you must create and protect the token yourself.

See Use the API for the authentication format and scope of every endpoint.

Permissions for managing tokens

Action	Permission
View existing tokens	service_token.view
Create a token	service_token.create
Revoke a token	service_token.delete