Using Service Accounts

1. Creating Service Accounts

Field	Description	Example
name	Name of the service account	`my-service-account`
role	Role assigned to the service account	`Editor`
tokensLimit	Maximum number of tokens that can be created for this service account	`10`

Example: Create Service Account via API

{
  "name": "my-service-account",
  "role": "Editor",
  "tokensLimit": 10
}

Note: Service accounts are created under the grafana organization by default.

2. Generating Service Account Tokens

Property	Value	Description
serviceAccount.name	`my-service-account`	Name of the service account to generate token for
token.ttl	`24h`	Time-to-live for the generated token (default: 24h)
token.scopes	`["datasource:read", "dashboard:read"]`	Scopes to grant the token (e.g., read access to data sources and dashboards)

Example: Generate Service Account Token via API

curl --request POST \
  --url 'http://localhost:3000/api/serviceaccounts/1/tokens' \
  --header 'Authorization: Bearer <admin-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{\n  "name": "my-token",\n  "secondsToLive": 86400\n}'

Note: The generated token will be returned in the response body as a JSON Web Token (JWT) and must be stored securely.

3. Setting Service Account Roles

Role	Description	Permissions	Notes
Admin	Full access to all Grafana features and data	All permissions	Use with caution in production environments
Editor	Can create, edit, and delete dashboards and panels	Read and write access to dashboards, folders, and data sources	Best for users who manage content but don't configure Grafana
Viewer	Can view dashboards and data but not make changes	Read-only access to dashboards, folders, and data sources	Best for users who only need to observe metrics and dashboards
Grafana Admin	Full administrative control over Grafana instance	All permissions including user management and configuration	Reserved for system administrators

Example: Assigning Admin Role to Service Account

curl -X POST "http://localhost:3000/api/serviceaccounts/1/roles" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "Admin"}'

Note: Service account roles can be managed via the Grafana UI or API. Ensure that the service account has the minimum required permissions to perform its tasks.

4. Managing Token Expiration

Property	Value	Description
token.maxTTL	`24h`	Maximum time a token can be valid. Default is 24 hours.
token.inactivityTimeout	`30m`	Time after which an inactive token is revoked. Default is 30 minutes.
token.rotationEnabled	`false`	Whether to automatically rotate tokens. Default is false.

Example: Setting Token Expiration

{
  "token": {
    "maxTTL": "48h",
    "inactivityTimeout": "1h"
  }
}

Note: Token expiration settings can be configured at the service account level or globally in Grafana's configuration.

5. Rotating Service Account Tokens

Token	Expiration	Action
service-account-token	`30d`	Rotate after 30 days

Example: Rotating Service Account Token

curl -X POST \
  "http://localhost:3000/api/serviceaccounts/1/tokens" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"name": "new-token", "secondsToLive": 2592000}'

Note: Tokens are valid for 30 days by default. Rotate tokens regularly to maintain security.

6. Revoking Service Account Tokens

Token ID	Status	Action
sa-token-12345	Active
sa-token-67890	Expired

Example: Revoke a Service Account Token via API

curl -X DELETE \
  "http://localhost:3000/api/serviceaccounts/123/tokens/456" \
  -H "Authorization: Bearer <your-api-token>"

Note: Revoked tokens will no longer be valid for authentication. Ensure all services using the token are updated to use a new token.

7. Migrating from API Keys

When migrating from API keys to service accounts in Grafana, consider the following steps and implications:

Aspect	API Keys	Service Accounts
Authentication Method	`Authorization: Bearer <API_KEY>`	`Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>`
Token Expiry	API keys do not expire by default	Service account tokens can be configured with expiration
Permissions	Global permissions based on user role	Granular permissions via roles and teams
Management	Managed via user profile or API	Managed via dedicated service account UI or API

Example: Migrating API Key to Service Account

# Step 1: Create a service account
curl -X POST "http://localhost:3000/api/serviceaccounts" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "MigratedServiceAccount", "role": "Viewer"}'

# Step 2: Create a token for the service account
curl -X POST "http://localhost:3000/api/serviceaccounts/123/tokens" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "MigratedToken", "secondsToLive": 3600}'

# Step 3: Use the new token in your client
curl -X GET "http://localhost:3000/api/datasources" \
  -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>"

Note: Ensure that all services using API keys are updated to use the new service account tokens before deprecating the old keys.

Warning: API keys with admin privileges should be carefully reviewed and replaced with service accounts having equivalent or more restrictive permissions.

8. Using Service Accounts for Automation

Property	Description	Example
serviceAccount.name	Name of the service account	`"automation-sa"`
serviceAccount.tokenTTL	Time-to-live for the token in seconds	`3600`
serviceAccount.permissions	Permissions assigned to the service account	`["read", "write"]`

Example: Create Service Account Token

curl -X POST \
  "http://localhost:3000/api/serviceaccounts/1/tokens" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"name": "automation-token", "secondsToLive": 3600}'

Example: Use Service Account Token in Automation Script

const axios = require("axios");

const token = "<service-account-token>";
const grafanaUrl = "http://localhost:3000";

axios.get('' + grafanaUrl + '/api/dashboards/home', {
  headers: {
    Authorization: `Bearer ${token}`
  }
}).then(response => {
  console.log("Dashboard loaded successfully");
});

Note: Service account tokens are valid for the duration specified in secondsToLive. Renew tokens before expiration to avoid automation failures.

Warning: Never hardcode service account tokens in scripts or version control. Use environment variables or secure vaults.

9. Auditing Service Account Usage

Field	Description	Example
serviceAccount.name	Name of the service account	`monitoring-sa`
serviceAccount.token	Token used for authentication	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
serviceAccount.lastUsed	Timestamp of last usage	`2026-01-15T10:30:00Z`
serviceAccount.permissions	Permissions granted to the service account	`read, write`

Example: Fetching Service Account Usage Logs

curl -H "Authorization: Bearer <admin-token>" \
  "http://localhost:3000/api/serviceaccounts/usage"

Note: Audit logs for service accounts are stored in Grafana's internal logging system and can be accessed via the grafana.log file or external log aggregation tools.

Key Points for Auditing Service Accounts

Service account tokens are rotated automatically every 90 days.
Access logs for service accounts can be enabled via log.level configuration.
Use Grafana's built-in audit logging to track token usage and permissions changes.

10. Setting Service Account Permissions

Permission	Description	Required Role	Notes
serviceaccounts:read	Read access to service accounts	Viewer	Allows viewing service account details and metadata
serviceaccounts:write	Write access to service accounts	Editor	Allows creating, updating, and deleting service accounts
serviceaccounts:delete	Delete access to service accounts	Admin	Allows permanent deletion of service accounts
serviceaccounts:token:read	Read access to service account tokens	Viewer	Allows viewing tokens associated with a service account
serviceaccounts:token:create	Create new tokens for service accounts	Editor	Allows generating new authentication tokens for a service account
serviceaccounts:token:delete	Delete tokens for service accounts	Editor	Allows revoking existing tokens for a service account

Example: Assigning Permissions via API

curl -X POST "http://localhost:3000/api/access-control/users/1/permissions" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      {
        "action": "serviceaccounts:read",
        "scope": ""
      },
      {
        "action": "serviceaccounts:token:create",
        "scope": ""
      }
    ]
  }'

Note: Service account permissions can also be managed through the Grafana UI under Configuration > Service Accounts.