Service Accounts

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.

Some service accounts are provisioned by SigNoz integrations, such as the one used by the SigNoz AWS agent. These accounts have the signoz-viewer role, which gives read-only access. The agent needs nothing more.

Prerequisites

• A role with the required transactions. See the Transactions Reference 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.

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. For a complete list of transactions each role grants, see the Transactions Reference.

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.

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.

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.

Delete a Service Account

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

Next Steps

• Authorization Overview — Understand how access control works in SigNoz
• Roles — Create and manage roles
• Transactions Reference — Look up transactions for each resource
• Single Sign-On (SSO) — Configure SSO for your organization
• SigNoz MCP Server — Use service account keys to connect AI tools to SigNoz via MCP
• SigNoz Operator — Use a service account key to manage SigNoz resources from Kubernetes
• Multi-Tenant Observability: Serve Customer Data via API — Use one service account per customer to serve their data in your product