> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API tokens and public API

> Create, inventory, test, rotate, and revoke personal API tokens safely, then use the public API reference for endpoint-specific integration work.

An API token is a personal server-to-server credential. It lets an integration authenticate as the member who created it; it is not a shared organization password, a way to bypass normal authorization, or a substitute for designing an integration with an accountable owner.

For the Directorate of Citizen Services, give every connector a named responsible team, an approved purpose, an expiry/review date, and a documented replacement path. For example, a service-reporting connector can be owned by the Infrastructure Team and limited to the approved reporting work; it must not become a reusable credential copied between teams or environments.

This page covers token governance and lifecycle. Use [Public API reference](/reference/public-api) for the supported endpoint contract, request shapes, and endpoint-specific authorization behaviour.

## Goal

Create a traceable token for one integration, capture the secret exactly once in an approved secret store, confirm a minimal connection without using real citizen data, and revoke or replace the credential when its owner, purpose, or risk changes.

## Access, ownership, and administrative boundaries

Every signed-in member can manage their own tokens. The API-token page can also expose organization-wide controls, but only when the member has the relevant assigned verb.

| Action                        | Who can do it                                        | What to verify                                                                                                 |
| ----------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Create a token                | The signed-in member creating their personal token   | The member is the accountable owner of the integration                                                         |
| View **My tokens**            | The token owner                                      | Name, state, expiry, hint, and last-use information are expected; the secret is not recoverable from this list |
| View **Organization tokens**  | A member with the **api\_tokens.admin\_list** verb   | The request is for inventory/audit, not casual credential browsing                                             |
| Revoke own active token       | Its owner                                            | The exact integration has a tested replacement or approved shutdown plan                                       |
| Revoke another member’s token | A member with the **api\_tokens.admin\_revoke** verb | Owner, token, incident/change reason, and effect on the integration are confirmed                              |

These verbs should be assigned through a reviewed role and appropriate organization scope. Do not turn on organization-wide inventory or revocation merely because a person supports an integration; it reveals operational metadata and can interrupt a service.

## What the token page stores and shows

| Item       | Meaning                                                     | Safe handling                                                                 |
| ---------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Token name | Human-readable identity for the connector                   | Include system, environment, purpose, and accountable owner                   |
| State      | **Active**, **expired**, or **revoked**                     | Treat expired/revoked as a lifecycle result, not an error to bypass           |
| Expiry     | Default one-year expiry, no expiry, or a future custom date | Prefer a reviewed expiry; use no expiry only with an explicit policy decision |
| Hint       | A short ending fragment that helps identify a token         | It is not a usable secret and must not be treated as proof of possession      |
| Last used  | The most recent observed use, if any                        | Investigate unexpected use before changing permissions or expiry              |
| Owner      | Visible in the authorized organization inventory            | Use it to identify the accountable member, not to share their credential      |

The service generates a versioned token value and stores a cryptographic hash plus a short hint. The full secret is displayed only immediately after creation. Closing that notice does not provide a recovery route; create a replacement and revoke the lost token instead.

## Before creating a token

1. Define one integration purpose and name its operational owner. A good name is **Citizen-service reporting connector — Infrastructure Team — production**; avoid vague names such as **Integration** or a person’s nickname.
2. Confirm the target environment, approved public API operations, data classification, and receiving system. A token must not be used to move citizen data into an unapproved system.
3. Confirm the token owner has only the normal roles and scopes that the integration actually needs. The creation dialog collects a name and expiry; it does not create a separate broad token-scope model.
4. Choose an expiry and renewal owner. The default is one year; a custom date must be in the future. A non-expiring token needs an explicit exception and recurring review.
5. Prepare an approved secret manager entry and access group before clicking **Create token**. Do not plan to copy the secret into a ticket, chat, email, spreadsheet, source repository, template, or screenshot.
6. Plan a small non-production verification and a rollback: know which token to revoke if the test sends an unexpected request.

## Create and capture a token

Open **Administration → API tokens and public API**, stay on **My tokens**, and select **Create token**.

1. Enter the precise token name and choose **One year**, **No expiry**, or **Custom** expiry. For a temporary test, use a short custom expiry where policy allows.
2. Create the token. Review the generated secret in the one-time notice while no one else can view your screen.
3. Copy it directly into the prepared secret-manager record. Store the owner, purpose, target environment, creation time, expiry, and rotation/review date next to the secret, but never the secret in ordinary documentation.
4. Close the notice after confirming the secret manager has accepted it. The token list will show only a hint, never the complete value.
5. Run the smallest approved connection check using a synthetic record or a read-only/non-mutating operation documented in the public API reference.
6. Refresh **My tokens** and confirm the expected token remains active. Where a request has reached the service, confirm the last-used value is plausible for the controlled test.

Use a placeholder in internal runbooks, never a live value:

```http theme={null}
Authorization: Bearer KOS_TOKEN_FROM_APPROVED_SECRET_MANAGER
```

Replace the placeholder only in the integration runtime or secure test environment. Do not paste a real token into a browser address bar, an expression, a document-template field, or a screenshot.

## Controlled Directorate example

The Infrastructure Team needs a nightly report of aggregate request volumes for the Directorate. The accountable engineer first confirms the approved public API operation, the report’s data-minimization rules, and the engineer’s underlying access. They create a token named **Citizen-service reporting connector — Infrastructure Team — production** with an approved expiry and put it in the production secret manager.

Before enabling the scheduled connector, they run one allowed request against a synthetic training record or an approved aggregate-only test. They verify the expected response, inspect the token’s last-used information, and confirm no write, public publication, or unintended dataset was involved. The integration owner records the token hint and review date in the change record, not the secret. If the test is not understood, they revoke the token before investigating further.

## Inventory, rotation, and revocation

Review token inventory on a regular governance cadence and immediately after an owner transfer, suspected exposure, unexplained use, staff departure, or connector retirement.

1. Use **My tokens** for personal inventory. Authorized administrators can select **Organization tokens** only when they have **api\_tokens.admin\_list**.
2. Compare each name, owner, state, expiry, and last-used value with the integration register. Flag vague names, tokens with no owner, unplanned no-expiry settings, expired values, and unexpected activity.
3. Rotate by creating a new named token, storing it securely, updating the integration, and proving a small controlled request with the new credential.
4. Revoke the old token only after the replacement is known to work. Revocation stops the token immediately; it is not reversible.
5. For a suspected leak, revoke first, preserve the relevant audit/change evidence, determine where the value appeared, and create a replacement only after the exposure path is controlled.
6. Remove decommissioned integrations from schedules and secret stores according to policy. A revoked token should not remain an unexplained operational dependency.

Never “rotate” by renaming an existing token, extending an expiry without review, or sharing a token with a replacement owner. Tokens are bound to their creating member and should be replaced under the new accountable owner.

## Safe validation

| Test                    | Expected result                                                                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| One-time secret capture | The secret is copied to the approved secret manager once and does not reappear in the token list                                                                     |
| Minimal connection      | A documented, safe request succeeds only for the approved integration purpose                                                                                        |
| Ownership review        | The token name and authorized inventory identify the accountable member and environment                                                                              |
| Permission boundary     | A member without **api\_tokens.admin\_list** cannot open organization-wide inventory; one without **api\_tokens.admin\_revoke** cannot revoke another member’s token |
| Expiry                  | A token with a passed expiry is shown as expired and is replaced through the approved lifecycle                                                                      |
| Revocation              | The revoked token stops working immediately; the tested replacement continues if one was configured                                                                  |

## Troubleshooting

| Symptom                                          | Check first                                                                                     | Safe response                                                                                            |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| The full token was lost after closing the notice | Secret-manager record and whether the integration was configured                                | Do not ask support to recover it; create a new token, update the integration, then revoke the lost token |
| Organization tokens tab is missing               | Assigned **api\_tokens.admin\_list** verb and current organization                              | Request the narrow reviewed role; do not use another administrator’s session                             |
| Revoke is unavailable for another owner’s token  | Assigned **api\_tokens.admin\_revoke** verb, token state, and current organization              | Have an authorized administrator perform the reviewed revocation                                         |
| A token is expired                               | Expiry date, integration owner, and renewal decision                                            | Create a replacement with an approved future expiry and update the connector                             |
| Last-used information is unexpected              | Token name/hint, owner, time window, integration logs, and change record                        | Treat it as a security investigation; revoke if exposure is plausible                                    |
| The public API request fails                     | Exact documented endpoint/method, token state, target environment, and underlying authorization | Test a smaller approved request and use the public API reference; do not broaden access blindly          |

## Related guides

* Use endpoint-specific integration guidance in [Public API reference](/reference/public-api).
* Configure least-privilege inventory/revocation access in [Roles and scopes](/admin/roles-and-scopes).
* Govern files produced by integrations in [Export jobs](/admin/export-jobs).
* Review unavailable settings in [Permissions and availability](/reference/permissions-and-availability).

![KayanOS API token lifecycle settings for the Directorate of Citizen Services, without a credential shown.](https://kayanos.app/docs-images/en/admin/api-tokens-and-public-api.png)