Service Accounts

Create and manage service accounts for AI staff members and programmatic API access.

Service accounts are non-human principals that authenticate with sa_ prefixed tokens. They appear as members in the organization and can participate in chat, be assigned tasks, and create automations (which are automatically placed in pending_approval status for human review).

All service account endpoints require the org.members.manage permission.

Each service account is backed by a provider that determines how it responds in chat:

Provider	Description
openrouter	AI model accessed via OpenRouter. Requires openrouter_model.
cursor	Cursor Cloud Agent. Optionally accepts cursor_default_repo_url and cursor_default_ref.

---

List service accounts

GET /api/v1/organizations/{orgId}/service-accounts

Returns all service accounts in the organization.

Path parameters

orgId · string · required

Organization UUID.

Example

curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "service_accounts": [
    {
      "id": "018e1234-abcd-7000-8000-0000000000b0",
      "organization_id": "018e1234-abcd-7000-8000-000000000000",
      "user_id": "018e1234-abcd-7000-8000-0000000000c0",
      "name": "Aria",
      "created_by": "018e1234-abcd-7000-8000-000000000050",
      "created_at": "2024-03-01T10:00:00Z",
      "provider": "openrouter",
      "openrouter_model": "nvidia/nemotron-3-super-120b-a12b:free",
      "cursor_default_repo_url": null,
      "cursor_default_ref": null
    }
  ]
}

service_accounts[].id · string

Service account UUID.

service_accounts[].organization_id · string

Organization UUID.

service_accounts[].user_id · string

UUID of the backing user principal. Use this ID for @mentions and assignee_user_id.

service_accounts[].name · string

Display name shown in the UI.

service_accounts[].created_by · string

UUID of the human user who created this service account.

service_accounts[].provider · string

"openrouter" or "cursor".

service_accounts[].openrouter_model · string

OpenRouter model identifier (provider openrouter only).

service_accounts[].cursor_default_repo_url · string

Default repository URL for Cursor Cloud Agent (provider cursor only), or null.

service_accounts[].cursor_default_ref · string

Default git ref for Cursor Cloud Agent (provider cursor only), or null.

---

Create a service account

POST /api/v1/organizations/{orgId}/service-accounts

Creates a new service account, its backing user principal, and an initial sa_ token. The token is returned once in the response and cannot be retrieved again. Store it securely.

Path parameters

orgId · string · required

Organization UUID.

Request body

name · string · required

Display name for the AI staff member.

provider · string

"openrouter" (default) or "cursor".

openrouter_model · string

OpenRouter model identifier. Required when provider is openrouter. Defaults to "nvidia/nemotron-3-super-120b-a12b:free" if omitted.

cursor_default_repo_url · string

Default repository URL passed to Cursor Cloud Agent invocations. Optional; the agent resolves the repo from the space’s git links when unset.

cursor_default_ref · string

Default git ref (branch or commit SHA) for Cursor Cloud Agent. Optional.

role_ids · array

List of role UUIDs to assign to this service account. If omitted, system default roles apply.

Example — OpenRouter AI staff

curl -X POST https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aria",
    "provider": "openrouter",
    "openrouter_model": "anthropic/claude-3.5-sonnet"
  }'

Example — Cursor Cloud Agent

curl -X POST https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CursorBot",
    "provider": "cursor",
    "cursor_default_repo_url": "https://github.com/acme/api",
    "cursor_default_ref": "main"
  }'

Response 201 Created

{
  "service_account": {
    "id": "018e1234-abcd-7000-8000-0000000000b1",
    "organization_id": "018e1234-abcd-7000-8000-000000000000",
    "user_id": "018e1234-abcd-7000-8000-0000000000c1",
    "name": "Aria",
    "created_by": "018e1234-abcd-7000-8000-000000000050",
    "created_at": "2024-03-20T10:00:00Z",
    "provider": "openrouter",
    "openrouter_model": "anthropic/claude-3.5-sonnet"
  },
  "token": "sa_4a7f3c8b2e1d6a9f0c5b3e7d2a1f4c8b9e3d6a7f2c1b5e8d3a0f7c4b2e9d6a1f"
}

service_account · object

The created service account object.

token · string

The sa_ prefixed API token. This is the only time this value is returned. Store it immediately.

---

Update a service account

PATCH /api/v1/organizations/{orgId}/service-accounts/{serviceAccountId}

Updates provider-specific fields. All fields are optional.

Path parameters

orgId · string · required

Organization UUID.

serviceAccountId · string · required

Service account UUID.

Request body

provider · string

Change the provider: "openrouter" or "cursor".

openrouter_model · string

New OpenRouter model identifier. Set to "" to clear (provider must then be changed to cursor).

cursor_default_repo_url · string

New default repository URL. Set to "" to clear.

cursor_default_ref · string

New default git ref. Set to "" to clear.

Example

curl -X PATCH \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts/YOUR_SA_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"openrouter_model": "openai/gpt-4o"}'

Response 200 OK

{
  "service_account": {
    "id": "018e1234-abcd-7000-8000-0000000000b1",
    "name": "Aria",
    "provider": "openrouter",
    "openrouter_model": "openai/gpt-4o",
    ...
  }
}

---

Delete a service account

DELETE /api/v1/organizations/{orgId}/service-accounts/{serviceAccountId}

Removes the service account, its backing user, role assignments, and organization membership. The sa_ token is invalidated. This action is irreversible.

Path parameters

orgId · string · required

Organization UUID.

serviceAccountId · string · required

Service account UUID.

Example

curl -X DELETE \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/service-accounts/YOUR_SA_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204 No Content

---

Token lifecycle

The sa_ token is generated once at creation time. There is no rotation endpoint in the current API version. To rotate a token, delete the service account and create a new one.

Service account tokens do not expire. They are validated by SHA-256 hash lookup and may optionally have an expires_at set in the database.