---
title: "Create Service Account"
method: POST
path: "/service-accounts"
tags: ["Service Accounts"]
---

# Create Service Account

`POST /service-accounts`

Mint a service account token. The plaintext token is returned exactly once.

## Request body

- ServiceAccountCreate
  - `name` string, required — Machine identity name (lowercase slug), e.g. 'claude-code' or 'github-actions'
  - `scopes` ScopeItem[], nullable — Scopes granted to the token, as {scope, effect} objects (the shared RBAC write shape; token scopes are grants, so only effect='allow' is accepted). Defaults to run and read scopes: agents:run, teams:run, workflows:run, sessions:read
    - `scope` string, required — Scope string, e.g. 'agents:*:run'
    - `effect` 'allow' | 'deny' — 'allow' or 'deny'
  - `expires_in_days` integer, nullable — Days until the token expires (default: 90)
  - `never_expires` boolean — Mint a non-expiring token. Must be set explicitly; overrides expires_in_days.
  - `allow_privileged_scopes` boolean — Required to grant privileged scopes: any write or delete action, the admin scope, or any service_accounts scope. Privileged tokens must be deliberate, never accidental.

## Response `201`

Successful Response

- ServiceAccountCreateResponse — Returned once, at creation. The token is never retrievable again.
  - `id` string, required
  - `name` string, required
  - `principal` string, required — The user_id attached to runs made with this token, e.g. 'sa:claude-code'
  - `user_id` string, nullable — The user this account belongs to; None for workspace-level accounts. Distinct from created_by, which records who minted the token.
  - `token_prefix` string, required — First characters of the token, for display only
  - `scopes` ScopeSchema[] — Scopes granted to the token, in the shared RBAC read shape
    - `id` string, nullable — Scope id (always null here; kept for shape parity with the cloud RBAC API, which addresses scopes individually)
    - `raw` string, required — Original scope string, e.g. 'agents:*:run'
    - `namespace` string, required — Resource namespace, e.g. 'agents'
    - `sub_namespace` string, nullable — Specific resource id or wildcard '*'
    - `permission` string, required — Action, e.g. 'read' / 'run' / 'write'
    - `value` string — 'allow' or 'deny'
  - `created_at` integer, required
  - `expires_at` integer, nullable
  - `last_used_at` integer, nullable
  - `revoked_at` integer, nullable
  - `created_by` string, nullable
  - `token` string, required — The plaintext token. Shown exactly once - store it securely now.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agno/apis/agno-api-reference.md) · [All operations](https://skmtc.net/agno/apis/agno-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agno/agno-api-reference/revisions/5f6149d395d0/schema)