> For the complete documentation index, see [llms.txt](https://docs.snyk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snyk.io/platform-administration/service-accounts/manage-service-accounts-using-the-snyk-api.md).

# Manage service accounts using the Snyk API

You can manage service accounts using the [Snyk REST API](/developer-tools/snyk-api/reference/serviceaccounts.md).

{% hint style="info" %}
Specific permissions are required to perform all these tasks. For more information, visit [Service accounts-select a role](/platform-administration/service-accounts/service-accounts.md#select-a-role).
{% endhint %}

## Service account attributes

`id` - The ID of the service account.

`name` - A human-friendly name for the service account.

`auth_type` - Authentication strategy for the service account. The following options are available:

* `access_token` - The service account uses a Snyk access token with expiry.
* `api_key` - The service account uses a legacy Snyk API key (no expiry).
* `oauth_client_secret` - The service account uses an [OAuth 2.0 access token](https://docs.snyk.io/platform-administration/service-accounts/pages/pJGqAAN1qdb2uNLOtzjB#oauth-2.0-with-client-secret), retrieved with a client secret.
* `oauth_private_key_jwt` - The service account uses an [OAuth 2.0 access token](https://docs.snyk.io/platform-administration/service-accounts/pages/pJGqAAN1qdb2uNLOtzjB#oauth-2.0-with-private-key-jwt), retrieved with a JWT signed with a private key.

`role_id` - The role of the service account, which defines the permissions it has. Available roles can be found using the endpoint [List all roles in a group](/developer-tools/snyk-api/reference/groups-v1.md#group-groupid-roles).

`access_token_expires_at` - The expiry date of the access token in ISO-8601 format, for example, `2025-08-16T00:00:00Z`. The maximum expiry is one year from creation time. Required only when `auth_type` is `access_token`.

`jwks_url` - A JWKs URL hosting your public keys used to verify signed JWT requests. This must be `https`. Required only when `auth_type` is `oauth_private_key_jwt`.

`access_token_ttl_seconds` - The time, in seconds, that a generated access token will be valid for. Defaults to one hour if unset. Required only when `auth_type` is `oauth_client_secret` or `oauth_private_key_jwt`.

## Manage Group-level service accounts

### Get a list of service accounts in your Group

**Request**: `GET https://api.snyk.io/rest/groups/{groupId}/service_accounts`

**API endpoint:** [Get a list of group service accounts](/developer-tools/snyk-api/reference/serviceaccounts.md#groups-group_id-service_accounts-1)

This [paginated](/developer-tools/snyk-api/rest-api/about-the-rest-api.md#pagination) call returns an array of objects, each describing a service account.

### Create a service account for your Group

**Request**: `POST https://api.snyk.io/rest/groups/{groupId}/service_accounts`

**API endpoint:** [Create a service account for a group](/developer-tools/snyk-api/reference/serviceaccounts.md#groups-group_id-service_accounts)

This call creates a new service account. You pass a `role_id` in the JSON-formatted body of the request, which defines the permissions a service account can use. This role id can be found using the endpoint [List all roles in a group](/developer-tools/snyk-api/reference/groups-v1.md#group-groupid-roles). Roles can be re-used for multiple service accounts.

### Get a service account from your Group

**Request**: `GET https://api.snyk.io/rest/groups/{groupId}/service_accounts/{serviceAccountId}`

**API endpoint:** [Get a group service account](/developer-tools/snyk-api/reference/serviceaccounts.md#groups-group_id-service_accounts-serviceaccount_id-1)

This call returns details describing a specific service account.

### Update a service account in your Group

**Request**: `PATCH https://api.snyk.io/rest/groups/{groupId}/service_accounts/{serviceAccountId}`

**API endpoint:** [Update a group service account](/developer-tools/snyk-api/reference/serviceaccounts.md#groups-group_id-service_accounts-serviceaccount_id)

This call updates the details of a specific service account, at this time, the name of the service account.

### Delete a service account from your Group

**Request**: `DELETE https://api.snyk.io/rest/groups/{groupId}/service_accounts/{serviceAccountId}`

**API endpoint:** [Delete a group service account](/developer-tools/snyk-api/reference/serviceaccounts.md#groups-group_id-service_accounts-serviceaccount_id-secrets)

This call permanently deletes the specified service account and revokes its credentials.

### Manage a service account client secret for your Group

**Request**: `POST https://api.snyk.io/rest/groups/{groupId}/service_accounts/{serviceAccountId}/secrets`

**API endpoint:** [Manage a group service account’s client secret](/developer-tools/snyk-api/reference/serviceaccounts.md#groups-group_id-service_accounts-serviceaccount_id-secrets)

This call allows you to manage the client secret for `oauth_client_secret` service accounts. You can perform the following operations:

* `create` - generate a new client secret. A service account can have a maximum of two active secrets at a time.
* `delete` - delete an existing client secret. This requires putting `client_secret` in the request body. Deleting an existing client secret would render it invalid. A service account must have at least one active secret; calling delete with your last secret will fail.
* `replace` - simultaneously delete the existing client secret and generate a new secret. This option is recommended if your `client_secret` is compromised.

## Manage Organization-level service accounts

### Get a list of service accounts in your Organization

**Request**: `GET https://api.snyk.io/rest/orgs/{orgId}/service_accounts`

**API endpoint:** [Get a list of organization service accounts](/developer-tools/snyk-api/reference/serviceaccounts.md#orgs-org_id-service_accounts-1)

This [paginated](/developer-tools/snyk-api/rest-api/about-the-rest-api.md#pagination) call returns an array of objects, each describing a service account.

### Create a service account for your Organization

**Request**: `POST https://api.snyk.io/rest/orgs/{orgId}/service_accounts`

**API endpoint:** [Create a service account for an organization](/developer-tools/snyk-api/reference/serviceaccounts.md#orgs-org_id-service_accounts)

This call creates a new service account. You pass a `role_id` in the JSON-formatted body of the request, which defines the permissions a service account can use. This `role id` can be found using the endpoint [List all roles in a group](/developer-tools/snyk-api/reference/groups-v1.md#group-groupid-roles). Roles can be re-used for multiple service accounts.

### Get a service account from your Organization

**Request**: `GET https://api.snyk.io/rest/orgs/{orgId}/service_accounts/{serviceAccountId}`

**API endpoint:** [Get an organization service account](/developer-tools/snyk-api/reference/serviceaccounts.md#orgs-org_id-service_accounts-serviceaccount_id-1)

This call returns details describing a specific service account.

### Update a service account in your Organization

**Request**: `PATCH https://api.snyk.io/rest/orgs/{orgId}/service_accounts/{serviceAccountId}`

**API endpoint:** [Update an organization service account](/developer-tools/snyk-api/reference/serviceaccounts.md#patch-orgs-org_id-service_accounts-serviceaccount_id)

This call can update the details of a specific service account. The name of the service account is updated.

### Delete a service account from your Organization

**Request**: `DELETE https://api.snyk.io/rest/orgs/{orgId}/service_accounts/{serviceAccountId}`

**API endpoint:** [Delete a service account in an organization](/developer-tools/snyk-api/reference/serviceaccounts.md#orgs-org_id-service_accounts-serviceaccount_id-2)

This call permanently deletes the specified service account.

### Manage a service account client secret for your Organization

**Request**: `POST https://api.snyk.io/rest/orgs/{orgId}/service_accounts/{serviceAccountId}/secrets`

**API endpoint:** [Manage an organization's service account's client secret](/developer-tools/snyk-api/reference/serviceaccounts.md#orgs-org_id-service_accounts-serviceaccount_id-secrets)

This call allows you to manage the client secret for `oauth_client_secret` service accounts. You can perform the following operations:

* `create` - generate a new client secret. A service account can have a maximum of two active secrets at a time.
* `delete` - delete an existing client secret. This requires putting `client_secret` in the request body. Deleting an existing client secret would render it invalid. A service account must have at least one active secret; calling delete with your last secret will fail.
* `replace` - simultaneously delete the existing client secret and generate a new secret. This option is recommended if your `client_secret` is compromised.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.snyk.io/platform-administration/service-accounts/manage-service-accounts-using-the-snyk-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.