Skip to content
Radioso Docs home
Open app

Personal tokens and service accounts

Use a personal token for workspace automation you run as yourself. Use a service account for CI, production services, and jobs that need a stable non-human identity. Both authenticate role-aware REST API calls with Authorization: Bearer <token>.

Credential management itself is available only through a signed-in browser session. Mutation requests must also send X-Radioso-CSRF: 1; a bearer token cannot mint, reveal, rotate, or manage another credential.

Choose an identity

A personal token remains attached to your current workspace membership. Its role ceiling can be member or admin, but never exceeds your live role. Demotion takes effect on the next request; leaving and later rejoining the workspace does not revive an older token.

A service account is a workspace-owned identity with its own live member or admin role. It can have several credentials, so you can deploy a replacement before revoking the old credential. Disabling the account suspends every credential and keeps the account in Settings → API access, ready to re-enable. Archiving is the permanent choice: it invalidates every credential and retires the account from that list, while past audit events keep naming it.

Credentials created under an agent’s Channels settings are a different kind. They have no workspace role, are bound to exactly one agent and one audience (mcp or rest), and can only talk to that agent. A personal or service credential cannot be substituted for one of these agent credentials, and an agent credential cannot administer the workspace.

Open API access settings

List the capabilities and limits for the signed-in user:

bash
curl -sS -b cookies.txt \
  -H 'X-Workspace-Id: <workspace-id>' \
  https://api.radioso.ai/api/v1/account/workspaces/<workspace-id>/api-access

Every credential needs an expiry. A personal token can last up to 90 days; a service-account credential can last up to 365 days. The other default limits are 10 active personal tokens per user, 50 service accounts per workspace, and 5 active credentials per service account.

The list endpoints and Settings → API access show every credential that is still within its own lifetime, so the count on screen is the count that runs against those limits. A credential leaves the list once you revoke it or once its expiry passes, and a credential suspended by a disabled service account stays listed because re-enabling the account restores it.

Create a personal token

bash
personal_expiry="$(node -p 'new Date(Date.now() + 30 * 86400000).toISOString()')"
curl -sS -b cookies.txt -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Radioso-CSRF: 1' \
  -H 'X-Workspace-Id: <workspace-id>' \
  -d "{\"label\":\"CLI on laptop\",\"roleCeiling\":\"member\",\"expiresAt\":\"${personal_expiry}\"}" \
  https://api.radioso.ai/api/v1/account/workspaces/<workspace-id>/api-access/personal-tokens

The successful response contains secret once. Store it in a secret manager or protected environment variable before closing the response. List and detail responses contain only a safe prefix and lifecycle metadata; Radioso cannot recover the original secret.

Use the token from a server-side API client:

bash
curl -sS \
  -H 'Authorization: Bearer <personal-token>' \
  https://api.radioso.ai/api/v1/document

Create a service account

Open Settings → API access. An administrator or owner creates the stable identity and its first credential together. The form asks for the account name, role, and credential expiry; the server names the first credential Primary, so there is no second name to invent during setup.

bash
service_expiry="$(node -p 'new Date(Date.now() + 180 * 86400000).toISOString()')"
curl -sS -b cookies.txt -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Radioso-CSRF: 1' \
  -H 'X-Workspace-Id: <workspace-id>' \
  -d "{\"displayName\":\"Nightly ingestion\",\"role\":\"member\",\"credentialExpiresAt\":\"${service_expiry}\"}" \
  https://api.radioso.ai/api/v1/account/workspaces/<workspace-id>/api-access/service-accounts

This response also contains the credential secret once. Later credentials under the same service account authenticate as the same service identity while retaining their own IDs, safe prefixes, expiry settings, and last-use records.

For a deployment with no interruption:

  1. Issue an additional credential under the service account.
  2. Store and deploy the new value.
  3. Verify the workload with the new credential.
  4. Revoke the previous credential.

Immediate rotation is intended for a credential you must invalidate at once. It revokes the predecessor and returns one replacement with the same expiry setting.

Agent chat credentials are separate

Personal tokens and service-account credentials authenticate eligible workspace REST routes. They do not authenticate the MCP server or POST /api/v1/agents/{agentId}/chat.

Create a separate agent credential from the agent’s Channels → MCP or Channels → API card. Each credential has one audience, an expiry, and one agent. Its secret is returned once and stored as a hash. A signed-in user with permission to manage that agent can issue, rotate, or revoke it; the agent credential itself cannot manage credentials.

Common failure modes

  • 401 on a lifecycle endpoint means the interactive session is missing or invalid. Supplying another bearer token does not grant lifecycle access.
  • 403 means the signed-in user lacks the requested workspace capability or the requested role exceeds their live role.
  • 404 hides records outside the current account, workspace, or personal ownership boundary.
  • 409 means a quota was reached, the supplied revision is stale, or the requested service-account transition is invalid.
  • If an issue or rotation response is lost, find the inaccessible credential by its safe metadata and rotate or revoke it. The original secret remains unrecoverable.