Sign Up
Docs v2.0

Service Accounts

GET /orgs/:id/service-accounts — `read:service_accounts`.

GET
/orgs/{id}/service-accounts

List the service accounts of one organization. The caller must be a seated member holding read:service_accounts. Only an OIDC user JWT is admitted on this route; dtno_ organization API keys are not.

Authorization

user_jwt
headerAuthorizationBearer <token>

OIDC access token of a signed-in user (the dashboard/CLI login) used on the management plane: /me, /orgs*, /projects*, /invitations*, /roles, billing, audit, API-key, and service-account routes. Every management operation documents the org/project permission the authenticated member must hold.

Path Parameters

id*string

Organization id

Formatuuid

Query Parameters

include_archived?boolean

When true, return archived accounts as well. Mirrors include_revoked on the key list: retired principals are noise, shown only on request.

Response Body

Service accounts

application/json
  1. response
service_accounts*array<>
curl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/service-accounts'
{  "service_accounts": [    {      "archived_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",      "description": "string",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "live_key_count": 0,      "name": "string",      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",      "permissions": [        "string"      ],      "roles": [        "string"      ]    }  ]}

POST /orgs/:id/service-accounts — `write:service_accounts`.

POST
/orgs/{id}/service-accounts

Create a service account in one organization. The caller must be a seated member holding write:service_accounts, and the requested role set must stay within the caller's effective permissions. Only an OIDC user JWT is admitted on this route; dtno_ organization API keys are not.

Authorization

user_jwt
headerAuthorizationBearer <token>

OIDC access token of a signed-in user (the dashboard/CLI login) used on the management plane: /me, /orgs*, /projects*, /invitations*, /roles, billing, audit, API-key, and service-account routes. Every management operation documents the org/project permission the authenticated member must hold.

Path Parameters

id*string

Organization id

Formatuuid

Request Body

application/json
  1. body
description?string|null
name*string
roles*array<string>
Items1 <= items

Response Body

Created service account

application/json
  1. response
archived_at?|
Formatdate-time
created_at*string
Formatdate-time
created_by?|
Formatuuid
description?string|null
id*string
Formatuuid
live_key_count*integer
Formatint64
name*string
org_id*string
Formatuuid
permissions*array<string>
roles*array<string>
curl -X POST 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/service-accounts' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "roles": [    "string"  ]}'
{  "archived_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",  "description": "string",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "live_key_count": 0,  "name": "string",  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "permissions": [    "string"  ],  "roles": [    "string"  ]}

GET /projects/:id/service-accounts — which accounts can be minted keys in the project. On a non-default project, every account with a row (archived ones included, with `archived_at` set, so an operator can see and clean up a retired account's reach); on the default project every live account of the org, all `implicit: true` with no `added_at`.

GET
/projects/{id}/service-accounts

List which service accounts can hold API keys in one project. The caller must be able to enter the project and hold read:service_accounts in the owning organization. Only an OIDC user JWT is admitted on this route; dtno_ organization API keys are not.

Authorization

user_jwt
headerAuthorizationBearer <token>

OIDC access token of a signed-in user (the dashboard/CLI login) used on the management plane: /me, /orgs*, /projects*, /invitations*, /roles, billing, audit, API-key, and service-account routes. Every management operation documents the org/project permission the authenticated member must hold.

Path Parameters

id*string

Project id, or the literal default for the caller's default project alias

Response Body

Project service accounts

application/json
  1. response
service_accounts*array<>
curl -X GET 'https://example.com/projects/string/service-accounts'
{  "service_accounts": [    {      "added_at": "2019-08-24T14:15:22Z",      "archived_at": "2019-08-24T14:15:22Z",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "implicit": true,      "name": "string"    }  ]}

POST /projects/:id/service-accounts — add one account. Idempotent: `{"added": [id]}` when a row was inserted, `{"added": []}` when it already existed — the member routes' contract.

POST
/projects/{id}/service-accounts

Add one explicit service-account membership row to a project. The caller must be able to enter the project and hold write:service_accounts in the owning organization. Only an OIDC user JWT is admitted on this route; dtno_ organization API keys are not.

Authorization

user_jwt
headerAuthorizationBearer <token>

OIDC access token of a signed-in user (the dashboard/CLI login) used on the management plane: /me, /orgs*, /projects*, /invitations*, /roles, billing, audit, API-key, and service-account routes. Every management operation documents the org/project permission the authenticated member must hold.

Path Parameters

id*string

Project id, or the literal default for the caller's default project alias

Request Body

application/json
  1. body
service_account_id*string
Formatuuid

Response Body

Added project service-account ids

application/json
  1. response
added*array<>
curl -X POST 'https://example.com/projects/string/service-accounts' \  -H 'Content-Type: application/json' \  -d '{  "service_account_id": "81f92c7b-60ae-411e-bc6f-e2dc93db8886"}'
{  "added": [    "cfeefd5f-7de0-424c-ae7a-a31ee9b42101"  ]}

DELETE /projects/:id/service-accounts/:sa_id — remove the row and revoke the live keys the account owns in this project (D9, account side): an account that can no longer enter a project must not keep a credential to it. The account itself survives.

DELETE
/projects/{id}/service-accounts/{sa_id}

Remove one explicit service-account membership row from a project and revoke the account's keys in that project. The caller must be able to enter the project and hold write:service_accounts in the owning organization. Only an OIDC user JWT is admitted on this route; dtno_ organization API keys are not.

Authorization

user_jwt
headerAuthorizationBearer <token>

OIDC access token of a signed-in user (the dashboard/CLI login) used on the management plane: /me, /orgs*, /projects*, /invitations*, /roles, billing, audit, API-key, and service-account routes. Every management operation documents the org/project permission the authenticated member must hold.

Path Parameters

id*string

Project id, or the literal default for the caller's default project alias

sa_id*string

Service account id

Formatuuid

Response Body

Removed project service account

application/json
  1. response
removed*string
Formatuuid
revoked_keys*integer
Range0 <= value
curl -X DELETE 'https://example.com/projects/string/service-accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08'
{  "removed": "b07f53d7-69c3-4e70-b8bd-5f0f78ddacb1",  "revoked_keys": 0}

GET /service-accounts/:sa_id — `read:service_accounts`.

GET
/service-accounts/{sa_id}

Read one service account. The caller must be a seated member holding read:service_accounts in the owning organization. Only an OIDC user JWT is admitted on this route; dtno_ organization API keys are not.

Authorization

user_jwt
headerAuthorizationBearer <token>

OIDC access token of a signed-in user (the dashboard/CLI login) used on the management plane: /me, /orgs*, /projects*, /invitations*, /roles, billing, audit, API-key, and service-account routes. Every management operation documents the org/project permission the authenticated member must hold.

Path Parameters

sa_id*string

Service account id

Formatuuid

Response Body

Service account

application/json
  1. response
archived_at?|
Formatdate-time
created_at*string
Formatdate-time
created_by?|
Formatuuid
description?string|null
id*string
Formatuuid
live_key_count*integer
Formatint64
name*string
org_id*string
Formatuuid
permissions*array<string>
roles*array<string>
curl -X GET 'https://example.com/service-accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08'
{  "archived_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",  "description": "string",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "live_key_count": 0,  "name": "string",  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "permissions": [    "string"  ],  "roles": [    "string"  ]}

PATCH /service-accounts/:sa_id — `write:service_accounts`. `roles` REPLACES wholesale rather than merging, exactly as a member's PATCH does, and a replacement that narrows runs the cascade below.

PATCH
/service-accounts/{sa_id}

Update one service account. The caller must be a seated member holding write:service_accounts; the route also enforces grant-within-caller and authority-over-account checks, and revokes out-of-scope project keys when roles narrow. Only an OIDC user JWT is admitted on this route; dtno_ organization API keys are not.

Authorization

user_jwt
headerAuthorizationBearer <token>

OIDC access token of a signed-in user (the dashboard/CLI login) used on the management plane: /me, /orgs*, /projects*, /invitations*, /roles, billing, audit, API-key, and service-account routes. Every management operation documents the org/project permission the authenticated member must hold.

Path Parameters

sa_id*string

Service account id

Formatuuid

Request Body

application/json
  1. body
description?string|null
dry_run?|

Rehearse: run the full path and the cascade, then roll back (PLAN-NARROWING-REVOCATION-WARNING.md). Absent means false. Not a change by itself: it does not count toward the at-least-one-field rule.

name?string|null
roles?array<string>|null

Response Body

Updated service account, or a dry-run preview when dry_run is true

application/json
  1. response
dry_run*boolean
revoked_keys*integer
Formatint64
Range0 <= value
curl -X PATCH 'https://example.com/service-accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
{  "dry_run": true,  "revoked_keys": 0}

DELETE /service-accounts/:sa_id — `delete:service_accounts`. A SOFT delete that cascade-revokes: `archived_at` is set, every live key the account owns is revoked in the same transaction, and each eviction is published post-commit. There is no un-archive (D9) — only each token's hash is stored, so restoring the principal would restore no working credential.

DELETE
/service-accounts/{sa_id}

Archive one service account and revoke every project API key it owns. The caller must be a seated member holding delete:service_accounts; the route also enforces authority over the account's current permissions. Only an OIDC user JWT is admitted on this route; dtno_ organization API keys are not.

Authorization

user_jwt
headerAuthorizationBearer <token>

OIDC access token of a signed-in user (the dashboard/CLI login) used on the management plane: /me, /orgs*, /projects*, /invitations*, /roles, billing, audit, API-key, and service-account routes. Every management operation documents the org/project permission the authenticated member must hold.

Path Parameters

sa_id*string

Service account id

Formatuuid

Response Body

Archived service account

application/json
  1. response
archived*string
Formatuuid
revoked_keys*integer
Range0 <= value
curl -X DELETE 'https://example.com/service-accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08'
{  "archived": "77b91e41-9233-4bb1-8a76-4d7d51910b08",  "revoked_keys": 0}

Computersfor Agents

Isolated sandboxes for agent code,
ready in under 100 ms.

Start for Free