> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Service accounts
A *service account* provides an identity that a service can use to access
Chronosphere APIs, Chronoctl, Terraform, and the Chronosphere Collector. Use service
accounts for automated, programmatic interactions, such as CI/CD, ingesting
telemetry, or automated queries. Chronosphere Observability Platform attributes all
actions that a service takes to its service account. A service account can't access
the user interface, only the APIs. Accounts can belong to
[*teams*](/administer/accounts-teams/teams).
When you create a service account, Chronosphere also creates a non-expiring API
token that the service account uses for authentication.
Service accounts are distinct from [*user accounts*](/administer/accounts-teams/user-accounts),
which provide identities for users who can also authenticate interactively and use
Chronosphere Observability Platform.
To use tools that require non-interactive authentication, such as Chronoctl,
Terraform, or the Chronosphere API, create a temporary
[personal access token](/administer/accounts-teams/personal-access-tokens) with the
same permissions as your user account. You can also assign service accounts to teams
with the `SysAdmin` role, which also grants those service accounts administrative
permissions.
For details about accounts and teams, see
[Accounts and Teams](/administer/accounts-teams).
For details about interactive user account authentication, see
[Authenticating with Observability Platform](/overview/authenticating).
## View service accounts
In the navigation menu, click ** Go to Admin** and
then select **Platform > Service Accounts**.
To return all service accounts and their label restrictions, use the [Chronoctl](/tooling/chronoctl)
`service-accounts list` command.
For example, to return all service accounts in JSON format, run:
```shell theme={null}
chronoctl service-accounts list --output=json
```
To complete this action with the Chronosphere API, use the
[`ListServiceAccounts`](/tooling/api-info/definition/operations/ListServiceAccounts) endpoint.
Because the Chronosphere API requires authentication, include an API token with your
`curl` request, as shown in the following example. For more details, see
[Create an API token](/tooling/api-info#create-an-api-token).
```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"
curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
-X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
```
Replace the following:
* *`TOKEN`*: Your API token.
* *`INSTANCE`*: The subdomain name for your organization's Observability Platform instance.
* *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
* *`ENDPOINT_PATH`*: The specific endpoint you want to access.
The service account list contains the following information:
* **Name:** The service account name.
* **Service account email:** The unique email user for this service account.
* **Created by:** The service account creator.
* **Restriction:** The type of
[restrictions](/administer/accounts-teams/service-accounts#create-a-restricted-service-account)
on this account. Unrestricted accounts don't have a value here.
* **Last used:** When this service token was last accessed. This field can be
inaccurate if more than 1000 service accounts are active.
* **Metric label:** For restricted accounts, the key/value label pair restriction.
If you have a service account token, and don't know which account it belongs to,
use the following Chronoctl command:
```shell theme={null}
chronoctl auth whoami --api-token=TOKEN
```
Replace *`TOKEN`* with your service account token.
## Create a service account
New service accounts can be one of the following types, each configured differently:
* An *unrestricted service account*, which grants full access to all Chronosphere
APIs and entities, including administration and monitoring features.
* A *restricted service account*, which grants certain permissions to access only
telemetry data, and optionally limiting displayed metrics to those with one or
a pair of specific, case-sensitive label names and values.
To use a service account with Chronoctl or Terraform, you must create an unrestricted
service account.
To use a service account with the Chronosphere Collector, create a restricted
write-only service account.
### Create an unrestricted service account
A service account can access the entire Chronosphere API, but this access doesn't
necessarily grant it all possible privileges. You can also assign the `SysAdmin`
role to the team that the service account belongs to, but doing so is required only
if the service account needs to create, modify, and delete accounts, teams, and
[certain resources](/administer/accounts-teams/teams#assign-team-roles-and-permissions).
You **must** be a member of a team with the `SysAdmin` role to create a new service
account.
Select from the following methods to create an unrestricted service account.
To create an unrestricted service account:
1. In the navigation menu, click ** Go to Admin**
and then select
**Platform > Service Accounts**.
2. Click **+ Service Account**. This opens the **Add Service Account** dialog.
3. In the **Service Account Name** field, enter a descriptive name for the service
account.
4. In the **Service Account Type** section, select **Unrestricted**.
5. Click **Save**.
After creating the service account, Chronosphere displays its secret token.
This is the only time Observability Platform displays the service account's token.
Store it securely. If you lose the token, you must delete and recreate the service
account to generate a new token.
To create and manage service accounts with [Chronoctl](/tooling/chronoctl),
the account you use must either be a member of a team with the
[`SysAdmin` role](/administer/accounts-teams/user-accounts#grant-system-administrator-sysadmin-privileges-to-users)
or an unrestricted service account.
1. Generate a templated service account resource with the
`chronoctl service-accounts scaffold` command:
```shell theme={null}
chronoctl service-accounts scaffold > service-account.yml
```
Replace `service-account.yml` with any valid filename.
2. Edit the generated template to configure the new service account. Remove
any fields that you don't need to configure.
For example, to configure an unrestricted service account with the
slug `ci-build-account` and name `CI Build Account`,
the resulting resource is:
```yaml service-account.yml theme={null}
api_version: v1/config
kind: ServiceAccount
spec:
slug: ci-build-account
name: CI Build Account
unrestricted: true
```
3. Create the resource by passing the file containing the resource to the
`service-accounts create` command.
```shell theme={null}
chronoctl service-accounts create -f service-account.yml
```
The command returns the service account resource, including its secret API
`token`:
```yaml theme={null}
api_version: v1/config
kind: ServiceAccount
spec:
slug: ci-build-account
name: CI Build Account
token: acc261....
email: 7da....@serviceaccount.chronosphere.io
unrestricted: true
```
This is the only time Observability Platform displays the service account's token.
Store it securely. If you lose the token, you must delete and recreate the service
account to generate a new token.
To create an unrestricted service account with [Terraform](/tooling/infrastructure/terraform),
use the `chronosphere_service_account` resource type and assign a `name` to use
in Observability Platform inside the resource declaration.
For example, this code creates a service account without any restrictions that
Terraform refers to as `all_access`:
```terraform theme={null}
resource "chronosphere_service_account" "all_access" {
name = "Terraform - Unrestricted"
}
```
1. Add the definition to a Terraform file.
2. Run this command to create the resource:
```shell theme={null}
terraform apply
```
Terraform stores the new service account's secret token in its state. To use the
token in other Terraform resources, use the `.token` field of the service account
resource.
Using the previous example, the token for the service account with the Terraform
resource name `all_access` is accessible at `chronosphere_service_account.all_access.token`.
To view the token, inspect your Terraform state file. For example, you can use the
[`jq`](https://stedolan.github.io/jq/) tool to filter service accounts in the state
file:
```shell theme={null}
jq '.resources[] | select(.type=="chronosphere_service_account")' terraform.tfstate
```
To complete this action with the Chronosphere API, use the
[`CreateServiceAccount`](/tooling/api-info/definition/operations/CreateServiceAccount) endpoint
and update the `service_account.unrestricted` key.
Because the Chronosphere API requires authentication, include an API token with your
`curl` request, as shown in the following example. For more details, see
[Create an API token](/tooling/api-info#create-an-api-token).
```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"
curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
-X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
```
Replace the following:
* *`TOKEN`*: Your API token.
* *`INSTANCE`*: The subdomain name for your organization's Observability Platform instance.
* *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
* *`ENDPOINT_PATH`*: The specific endpoint you want to access.
### Create a restricted service account
A restricted service account can access *only* the telemetry ingest and query APIs.
The account can't access any of the other APIs. It can't make configuration changes,
such as adding rules, creating monitors, or adding accounts.
You can also optionally define **Label Restrictions** on restricted accounts to
limit the account to querying or ingesting only specific labels or label-value pairs
when authenticating with the account's token.
The following types of restricted service accounts are available:
* **Read-only** accounts are permitted only to query data. If you also define
Label Restrictions, the account can query only metrics with the defined metric
label keys or key-value pairs.
* **Write-only** accounts are permitted only to ingest data. If you also define
Label Restrictions, the account can ingest only metrics with the defined metric
label keys or key-value pairs.
* **Read & write** accounts are permitted to both query and ingest data, following
any defined Label Restrictions.
Write-only accounts are based on the principle of least privilege. A robot whose only
job is to send ingest data to the server doesn't need query access.
Restricted, read-only service accounts are restricted to reading even if the service
account is added to a team with `Editor` or `SysAdmin` roles.
Restricted accounts using label restrictions force a label with a specific value to
be present on write, and allows queries that include only that label/value pair.
Label restrictions support a maximum of two key/value pairs.
Key/value pairs on individual service accounts must be unique. You can't set multiple
values for the same label key.
Observability Platform strips this label from query responses. Users with
a restricted service account aren't aware that they're viewing metrics
that match only the specified label.
Users see all other telemetry.
Select from the following methods to create a restricted service account.
To create a restricted service account, you must have administrative privileges.
1. In the navigation menu, click ** Go to Admin** and then select
**Platform > Service Accounts**.
2. Click **+ Service Account**. This opens the **Add Service Account** dialog.
3. In the **Service Account Name** field, enter a descriptive name for the
service account.
4. In the **Service Account Type** section, select **Restricted**. Observability
Platform displays additional fields for you to complete.
5. Complete the creation process based on your needs. Use the
**Label Restrictions** section to limit this account's metrics access to only
labels with one, or a pair of specific key/value pairs. Click **+Add Label**
to add a second key/value pair. Label restrictions are case sensitive.
6. Click **Save**.
After creating the service account, Observability Platform displays its secret token.
This is the only time Observability Platform displays the service account's token.
Store it securely. If you lose the token, you must delete and recreate the service
account to generate a new token.
To create a restricted service account with [Chronoctl](/tooling/chronoctl), use the
`service-accounts create` command.
Specify required values as command arguments:
* name (`--name`)
* permission (`--permission`). Valid `permission` values are:
* `READ`: Read-only access.
* `WRITE`: Write access.
* `READ_WRITE`: Read and write access.
You can also specify optional metric label arguments:
* label name (`--label-name`)
* label value (`--label-value`)
1. Generate a templated service account resource with the `service-accounts scaffold`
command:
```shell theme={null}
chronoctl service-accounts scaffold > service-account.yaml
```
Replace `service-account.yaml` with any valid filename.
2. Edit the generated template to configure the new service account. Remove any
fields that you don't need to configure.
For example, to configure a restricted service account that can read and write
only metrics with the label `tenant` and the value `name`, the resulting resource
is:
```yaml service-account.yml theme={null}
api_version: v1/config
kind: ServiceAccount
spec:
slug: tenant-name
name: tenant
metrics_restriction:
labels:
tenant: name
permission: READ_WRITE
```
3. Create the service account:
```shell theme={null}
chronoctl service-accounts create -f service-account.yml
```
The command returns the service account resource, including its secret API
`token`:
```yaml theme={null}
api_version: v1/config
kind: ServiceAccount
spec:
slug: tenant-name
name: tenant
metrics_restriction:
labels:
tenant: name
token: acc261....
email: 7da....@serviceaccount.chronosphere.io
```
This is the only time Observability Platform displays the service account's token.
Store it securely. If you lose the token, you must delete and recreate the service
account to generate a new token.
To create a restricted service account using
[Terraform](/tooling/infrastructure/terraform), use the
`chronosphere_service_account` resource type followed by a resource name, and include
a `restriction` section in the resource declaration.
You must add a `permission` value in the `restriction` section to define the
account's access. Valid `permission` values are:
* `READ`: Read-only access.
* `WRITE`: Write access.
* `READ_AND_WRITE`: Read and write access.
You can optionally add a `labels` value in the `restriction` section to additionally
restrict the service account's access to limit metrics to display only those that
have the specified label name and value.
For example, this code creates a restricted service account that Terraform refers to
as `restricted_labeled`, which can only read and write metrics with the label name
`tenant` and label value `name`:
```terraform theme={null}
resource "chronosphere_service_account" "restricted_labeled" {
name = "Terraform - Restricted, READ_AND_WRITE, labeled"
restriction {
permission = "READ_AND_WRITE"
labels = { "tenant" : "name" }
}
}
```
1. Add the definition to a Terraform file.
2. Run this command to create the resource:
```shell theme={null}
terraform apply
```
Terraform stores the new service account's secret token in its state. To use the
token in other Terraform resources, use the `.token` field of the service account
resource.
Using the previous example, the token for the service account with the Terraform
resource name `all_access` is accessible at `chronosphere_service_account.all_access.token`.
To view the token, inspect your Terraform state file. For example, you can use the
[`jq`](https://stedolan.github.io/jq/) tool to filter service accounts in the state
file:
```shell theme={null}
jq '.resources[] | select(.type=="chronosphere_service_account")' terraform.tfstate
```
To complete this action with the Chronosphere API, use the
[`CreateServiceAccount`](/tooling/api-info/definition/operations/CreateServiceAccount) endpoint.
Because the Chronosphere API requires authentication, include an API token with your
`curl` request, as shown in the following example. For more details, see
[Create an API token](/tooling/api-info#create-an-api-token).
```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"
curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
-X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
```
Replace the following:
* *`TOKEN`*: Your API token.
* *`INSTANCE`*: The subdomain name for your organization's Observability Platform instance.
* *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
* *`ENDPOINT_PATH`*: The specific endpoint you want to access.
#### Label restriction example
Label restrictions support a third-party use case, where Chronosphere is the first
party, and a Chronosphere customer (CompanyX) is the second party. A Chronosphere
customer's customer (CompanyA, CompanyB, or CompanyC) is the third party.
In this scenario, CompanyX uses one tenant with Chronosphere to store data about
CompanyA, CompanyB, and CompanyC, discriminated by some key (such as `third-party`)
with a value of `A`, `B`, or `C`.
Employees of CompanyX can see all of the data.
Employees of CompanyA get a restricted service account with a label restriction of
`third-party=A`. CompanyA doesn't know this key or this value. Whenever they send
data to Chronosphere, Chronosphere augments the writes with `third-party=A`. Whenever
CompanyA does queries, Chronosphere lets them see time series that include only
`third-party=A`, but Chronosphere strips this label before showing the time series to
employees of CompanyA.
## Delete a service account
Select from the following methods to delete a service account.
Users can modify Terraform-managed resources only by using Terraform.
[Learn more](/tooling/infrastructure/terraform#prevent-changes-to-managed-resources).
To delete a service account, you must have administrative privileges.
1. In the navigation menu, click ** Go to Admin** and then select
**Platform > Service Accounts**.
2. Select the checkboxes for one or more service accounts you want to delete.
3. Click ** Delete** at the top of the list of service
accounts.
To delete a service account with [Chronoctl](/tooling/chronoctl), the account you use must
either be a member of a team with the
[`SysAdmin` role](/administer/accounts-teams/user-accounts#grant-system-administrator-sysadmin-privileges-to-users), or
an unrestricted service account.
Use the `service-accounts delete` command, passing the account's slug as the `--slug`
argument.
For example, to delete a service account with the slug `tenant-name`:
```shell theme={null}
chronoctl service-accounts delete tenant-name
```
To delete a resource that's managed by [Terraform](/tooling/infrastructure/terraform):
1. Edit your Terraform configuration file to remove the pre-existing resource
definition.
2. Run this command to remove the resource from Observability Platform:
```shell theme={null}
terraform apply
```
To complete this action with the Chronosphere API, use the
[`DeleteServiceAccount`](/tooling/api-info/definition/operations/DeleteServiceAccount) endpoint.
Because the Chronosphere API requires authentication, include an API token with your
`curl` request, as shown in the following example. For more details, see
[Create an API token](/tooling/api-info#create-an-api-token).
```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"
curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
-X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
```
Replace the following:
* *`TOKEN`*: Your API token.
* *`INSTANCE`*: The subdomain name for your organization's Observability Platform instance.
* *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
* *`ENDPOINT_PATH`*: The specific endpoint you want to access.