# Service Accounts

Create and manage service accounts for programmatic API access in SigNoz

> For the complete documentation index, see [llms.txt](https://signoz.io/llms.txt). Markdown versions are also available by appending `.md` to documentation URLs.

Tags: SigNoz Cloud, Self-Hosted Enterprise, Self-Hosted Community

## Overview

Service accounts provide a secure way to grant programmatic API access to SigNoz without tying credentials to individual users. Use them for CI/CD pipelines, automation scripts, external integrations, and any non-human system that needs to interact with the SigNoz API.

## Prerequisites

- A role with the required transactions. See the [Transactions Reference](https://signoz.io/docs/manage/administrator-guide/iam/reference/transactions/) for the detailed transactions required for each service account action.

## Create a Service Account

### Step 1: Add the Service Account

1. Navigate to **Settings > Service Accounts**.
2. Click **New Service Account**.
3. Enter a name for the service account. Names must use only lowercase letters, numbers, and hyphens, and can be up to 50 characters long.
4. Click **Create** to add the service account.

> **Info**
>
> Service account names must be unique within the workspace.

![Service Accounts list page in SigNoz Settings](https://d3nu8xzr1i9u95.cloudfront.net/web/img/docs/service-account/list.webp)

Service Accounts list page

### Step 2: Assign a Role

1. Click the newly created service account to open its details.
2. In the **Overview** tab, use the **Roles** dropdown to assign one or more roles. You can assign any managed or custom role available in your organization.
3. Click **Save** to apply your changes.

The service account receives the union of all transactions from its assigned roles. For details on managed and custom roles, see [Roles](https://signoz.io/docs/manage/administrator-guide/iam/roles/). For a complete list of transactions each role grants, see the [Transactions Reference](https://signoz.io/docs/manage/administrator-guide/iam/reference/transactions/).

> **Info**
>
> You can copy the service account's ID from the **Overview** tab. You'll need it when granting transactions scoped to this service account (the **Only selected** selector on a custom role).

### Step 3: Generate an API Key

1. Open the service account and switch to the **Keys** tab.
2. Click **Add Key**.
3. Enter a descriptive name for the key (for example, `ci-pipeline-prod`).
4. Optionally, set an expiration date. Keys without an expiration remain valid until manually revoked.
5. Click **Create** to generate the key.

> **Info**
>
> Key names must be unique within the service account.

> **Warning**
>
> The key value is shown **only once** at creation time. Copy it immediately and store it in a secure location such as a secrets manager. You will not be able to retrieve it again.

![Key creation success screen showing the one-time key value](https://d3nu8xzr1i9u95.cloudfront.net/web/img/docs/service-account/create-key.webp)

Copy the key value before closing this dialog

### Step 4: Authenticate API Requests

Include the key in the `SIGNOZ-API-KEY` header when making API requests:

```
curl -X GET https://<SIGNOZ_URL>/api/v1/service_accounts/me \
  -H "SIGNOZ-API-KEY: <YOUR_SERVICE_ACCOUNT_KEY>"
```

Replace `<SIGNOZ_URL>` with your SigNoz instance URL and `<YOUR_SERVICE_ACCOUNT_KEY>` with the key you copied in Step 3.

## Validate

To confirm the service account key is working, run the following command and verify you receive a successful response:

```
curl -X GET https://<SIGNOZ_URL>/api/v1/service_accounts/me  \
  -H "SIGNOZ-API-KEY: <YOUR_SERVICE_ACCOUNT_KEY>"
```

A `200` status code indicates the key is valid and the service account has the required transactions. If you receive `401`, verify the key value is correct.

## Manage Existing Keys

### Revoke a Key

In the **Keys** tab, click the revoke icon next to the key you want to invalidate.

> **Warning**
>
> Revoking a key is permanent and takes effect immediately. Any system using the revoked key will lose API access.

### Update Key Expiration

To change the expiration date of an existing key:

1. Open the service account and navigate to the **Keys** tab.
2. Click on the key you want to update.
3. Modify the **Expiration Date** field. You can extend, shorten, or remove the expiration entirely.
4. Click **Save** to apply the changes.

> **Info**
>
> Updating the expiration date does not regenerate the key value. Existing integrations using the key will continue to work without any changes.

## Delete a Service Account

1. Open the service account you want to remove.
2. Click **Delete Service Account** and confirm the action.

> **Warning**
>
> Deleting a service account permanently revokes **all** of its associated keys. This action cannot be undone. Ensure no active systems depend on the account's keys before proceeding.

## Next Steps

- [Authorization Overview](https://signoz.io/docs/manage/administrator-guide/iam/overview/) — Understand how access control works in SigNoz
- [Roles](https://signoz.io/docs/manage/administrator-guide/iam/roles/) — Create and manage roles
- [Transactions Reference](https://signoz.io/docs/manage/administrator-guide/iam/reference/transactions/) — Look up transactions for each resource
- [Single Sign-On (SSO)](https://signoz.io/docs/manage/administrator-guide/sso/overview/) — Configure SSO for your organization
- [SigNoz MCP Server](https://signoz.io/docs/ai/signoz-mcp-server/) — Use service account keys to connect AI tools to SigNoz via MCP

More docs: /docs/sitemap.md