> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kontext.security/llms.txt
> Use this file to discover all available pages before exploring further.

# Service Accounts

> Create and manage service accounts for backend and CI/CD automation.

Service accounts authenticate using client credentials (client ID + secret) and act on behalf of the organization rather than a specific user. Use them for CI/CD pipelines, backend automation, and monitoring scripts.

## Endpoints

| Method   | Path                                  | Purpose                |
| -------- | ------------------------------------- | ---------------------- |
| `POST`   | `/service-accounts`                   | Create service account |
| `GET`    | `/service-accounts`                   | List service accounts  |
| `GET`    | `/service-accounts/:id`               | Get service account    |
| `POST`   | `/service-accounts/:id/rotate-secret` | Rotate secret          |
| `DELETE` | `/service-accounts/:id`               | Delete service account |

`id` path params are service account UUIDs (not the OAuth `clientId`).

## Create service account

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X POST https://api.kontext.security/api/v1/service-accounts \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "CI Pipeline",
      "description": "Used by GitHub Actions to manage integrations"
    }'
  ```

  ```typescript SDK theme={"system"}
  const { serviceAccount, credentials } = await client.serviceAccounts.create({
    name: "CI Pipeline",
    description: "Used by GitHub Actions to manage integrations",
  });

  // Credentials are only returned on create and rotate
  console.log(serviceAccount.id);
  console.log(credentials.clientId);     // "sa_<uuid>"
  console.log(credentials.clientSecret); // store this securely
  ```
</CodeGroup>

### Request body

| Field         | Type     | Required | Description                |
| ------------- | -------- | -------- | -------------------------- |
| `name`        | `string` | Yes      | Display name               |
| `description` | `string` | No       | Human-readable description |

### Response

The response includes a `credentials` object with `clientId` and `clientSecret`. The secret is only returned on create and rotate -- store it immediately.
Response shape: `{ "serviceAccount": { ... }, "credentials": { ... } }`

Use these credentials with the Management SDK:

```typescript theme={"system"}
import { KontextManagementClient } from "@kontext-dev/js-sdk/management";

const client = new KontextManagementClient({
  baseUrl: "https://api.kontext.security",
  credentials: {
    clientId: "sa_your-service-account-id",
    clientSecret: "your-service-account-secret",
  },
});
```

Or request a token directly:

```bash theme={"system"}
curl -X POST https://api.kontext.security/oauth2/token \
  -u "sa_client-id:client-secret" \
  -d "grant_type=client_credentials" \
  -d "scope=management:all"
```

## List service accounts

<CodeGroup>
  ```bash curl theme={"system"}
  curl https://api.kontext.security/api/v1/service-accounts \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { items, nextCursor } = await client.serviceAccounts.list();
  ```
</CodeGroup>

Returns all service accounts in the organization. Credentials are never included in list responses.

## Get service account

<CodeGroup>
  ```bash curl theme={"system"}
  curl https://api.kontext.security/api/v1/service-accounts/33333333-3333-4333-8333-333333333333 \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { serviceAccount } = await client.serviceAccounts.get(
    "33333333-3333-4333-8333-333333333333",
  );
  ```
</CodeGroup>

Returns metadata for the service account. Does not include credentials.

## Rotate secret

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X POST https://api.kontext.security/api/v1/service-accounts/33333333-3333-4333-8333-333333333333/rotate-secret \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { credentials } = await client.serviceAccounts.rotateSecret(
    "33333333-3333-4333-8333-333333333333",
  );
  console.log(credentials.clientSecret); // new secret
  ```
</CodeGroup>

Generates a new `clientSecret` and invalidates the previous one immediately. Any active tokens issued with the old secret continue to work until they expire, but no new tokens can be obtained with the old secret.

Store the new secret -- it will not be shown again.

## Delete service account

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X DELETE https://api.kontext.security/api/v1/service-accounts/33333333-3333-4333-8333-333333333333 \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  await client.serviceAccounts.revoke("33333333-3333-4333-8333-333333333333");
  ```
</CodeGroup>

Permanently deletes the service account and revokes all tokens associated with it. This action cannot be undone.