# Service accounts (/docs/reference/api/service-accounts)



Service accounts [#service-accounts]

All service-account methods require an organization administrator. Deletion requires a first-party session.

Create identities for automated workloads. A service account is not a credential. Assign an API key or federation rule to its ID to authenticate as that account.

GET `/v1/organizations/{organization_id}/service-accounts` [#get-v1organizationsorganization_idservice-accounts]

List service accounts. Requires an organization administrator..

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Request:

```bash
# List service accounts. Requires an organization administrator.
curl -X GET "https://api.rawtree.com/v1/organizations/22222222-2222-4222-8222-222222222222/service-accounts" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "organization_id": "22222222-2222-4222-8222-222222222222",
    "name": "event-worker",
    "description": null,
    "role": "member"
  }
]
```

Errors: `401`, `403`. See [API errors](/docs/reference/errors).

POST `/v1/organizations/{organization_id}/service-accounts` [#post-v1organizationsorganization_idservice-accounts]

Create a service account. The name cannot be changed after creation..

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field         | Location | Type               | Required | Notes                                                                       |
| ------------- | -------- | ------------------ | -------- | --------------------------------------------------------------------------- |
| `name`        | body     | string             | Yes      | Lowercase letters and digits separated by single hyphens; 1–128 characters. |
| `description` | body     | string or null     | No       | Optional description, up to 2000 UTF-8 bytes.                               |
| `role`        | body     | ServiceAccountRole | No       | —                                                                           |

Request:

```bash
# Create a service account. The name cannot be changed after creation.
curl -X POST "https://api.rawtree.com/v1/organizations/22222222-2222-4222-8222-222222222222/service-accounts" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "event-worker",
  "role": "member"
}'
```

Expected response: **HTTP 200**.

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "organization_id": "22222222-2222-4222-8222-222222222222",
  "name": "event-worker",
  "description": null,
  "role": "member"
}
```

Errors: `401`, `403`. See [API errors](/docs/reference/errors).

DELETE `/v1/organizations/{organization_id}/service-accounts/{id}` [#delete-v1organizationsorganization_idservice-accountsid]

Delete a service account from this organization..

Use a first-party user session. User OAuth, API keys, and workload tokens cannot delete a service account.

Request:

```bash
# Delete a service account from this organization.
curl -X DELETE "https://api.rawtree.com/v1/organizations/22222222-2222-4222-8222-222222222222/service-accounts/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer $RAWTREE_SESSION_TOKEN"
```

Expected response: **HTTP 200**.

```json
null
```

Errors: `401`, `403`. See [API errors](/docs/reference/errors).