Service Accounts

This guide explains how to create, manage, and authenticate with service accounts in OpenObserve.

Overview

A service account is a non-human account used for API access, automation, and integrations. It is an identity: you assign it roles and permissions, and it is issued a token for authentication. Because permissions attach to the account rather than to the token, you can rotate the token at any time without changing the account's access, and audit logs stay tied to a stable identity across rotations.

Availability differs by edition:

• Enterprise and Cloud: Service accounts have no permissions by default. Admins must assign roles explicitly.
• Open-source: Service accounts have full access by default.

Create a service account

1. From the IAM panel, select Service Accounts.
2. Click New service account.
3. Enter the Service account name: lowercase letters, numbers and hyphens (for example, ingest-bot). OpenObserve saves it as the Identifier <name>.<org_id>@sa.internal, which is the account's username.
4. Optionally, enter a Description, and on Enterprise and Cloud pick roles in Assign roles and groups in Add to user groups.
5. Click Save.
6. A token is generated and shown only once. Copy it (or use Download Token) and store it securely — it cannot be viewed again later; only a redacted version is shown (the first 4 characters followed by *). The dialog also shows ready-made cURL, Header and Environment Variable snippets.
7. If you did not assign roles or groups, grant them now. On Enterprise and Cloud this step is required before the service account can make any API calls.

Service accounts created before this naming scheme keep their original email as the identifier.

Grant access

Service accounts are principals just like users, so you grant them access the same way:

• Assign a role — go to IAM > Roles, open a role, and add the service account from its Service Accounts tab.
• Add to a user group — go to IAM > User Groups, open a group, and add the service account from its Service Accounts tab. The account inherits every role attached to that group.

Grant only the minimum access the integration needs.

Authenticate with the token

OpenObserve authenticates API requests using HTTP Basic auth, where the service account's identifier is the username and its token is the password.

curl -u "ingest-bot.<org_identifier>@sa.internal:YOUR_TOKEN" \
  "https://your-instance/api/<org_identifier>/streams"

To send the credential as a header instead, base64-encode identifier:token and pass it as Authorization: Basic <encoded>.

Rotate the token

You can rotate a service account's token at any time from the Service Accounts page by clicking Rotate Token in the account's row and confirming with Rotate token. A rotated token is also shown only once, so copy and store it securely. Rotating does not change the account's roles or identity — only the secret.

Rotating a token requires the Admin or Root role (or, with RBAC/OpenFGA enabled, explicit permission). Users without sufficient privileges receive a 403 error.

Which credential do I need?

OpenObserve issues a few different credentials. Use this table to pick the right one:

If you need role-based access to the general API, use a service account. If you only need to ship data in, use an ingestion token.