Create Service Account

Service account setup

Use a supported AgentOS-level database, as in the catalog server. See service account authorization for the authentication and scope configuration.

The account's sa:<name> principal identifies calls made by its token. It is distinct from created_by and the account's owner user_id. List responses contain metadata and token prefixes, not reusable plaintext credentials.

Mint a token

Creation requires actual security-key, JWT or PAT authentication, including on an otherwise open instance; anonymous requests return 401. For example, using the linked catalog server's shared key:

curl --fail-with-body http://127.0.0.1:7777/service-accounts \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"example-reader","scopes":[{"scope":"sessions:read","effect":"allow"}],"expires_in_days":30}'

The plaintext token is returned once. Keep it for the client that will use the account; subsequent lists cannot recover it.

allow_privileged_scopes=true acknowledges privileged grants but does not grant authority to mint them. A caller can grant only scopes they hold (403 otherwise). Unknown scopes return 400, and an active duplicate name returns 409.

curl --request POST 'https://example.com/service-accounts' \  --header 'Content-Type: application/json' \  --data-raw '{"name":"string"}'

{  "id": "string",  "name": "string",  "principal": "string",  "user_id": "string",  "token_prefix": "string",  "scopes": [    {      "id": "string",      "raw": "string",      "namespace": "string",      "sub_namespace": "string",      "permission": "string",      "value": "allow"    }  ],  "created_at": 0,  "expires_at": 0,  "last_used_at": 0,  "revoked_at": 0,  "created_by": "string",  "token": "string"}

{  "detail": [    {      "loc": [        "string"      ],      "msg": "string",      "type": "string",      "input": null,      "ctx": {}    }  ]}