Configure authorization and permissionsGrafana Cloud Access PoliciesAuthorize your service with an access policy and token

Authorize your service with an access policy and token

You can start managing Grafana Cloud Access Policies via the API or by using the Grafana Cloud Access Policies Plugin. Contact support to enable the plugin.

To use Grafana Cloud Access Policies, you need to:

  1. Create an access policy
  2. Create one or more tokens
  3. Add the token to your agent’s or Grafana data source’s configuration

Create an access policy

Following the principle of least privilege, an access policy should only have the necessary scopes. For example, since publishing metrics is done separately from reading metrics, consider having:

  • One access policy to read metrics
  • One access policy to write metrics

And similarly:

  • One access policy to read logs
  • One access policy to write logs

Depending upon how you are setting up your access policies, you may need to create more than one access policy and token.

To use the API, refer to the Create an access policy section of the Grafana Cloud API document.

To create an access policy using the Access Policies Plugin:

  1. Sign in to Grafana Cloud and start the stack where you wish to create the access policy.
  2. Select the Configuration (gear) icon in the left navigation to open the Configuration screen.
  3. Click the Cloud access policies tab, then select Create access policy.
  4. Enter a Display Name for the access policy.
  5. Optional: Update the Name field. This field is automatically populated with the Display name.
  6. Select one or more scopes for the policy.
  7. Add Label selectors, if desired. The label selectors use Prometheus labels. You can use operators like != and =.
    Tip: Refer to Using label-based access control for additional information.
  8. Select Create to add the access policy.

List tokens or organizations IDs

You will need to use the legacy API key to locate your organization and stack ID. If you are using the Cloud Access Policies Plugin, then the realm information is automatically populated.

To locate your stack IDs, you can use list stacks from the Grafana Cloud API document.

Create one or more access policy tokens

Any data source that you use with Grafana Cloud requires a token that is associated with an access policy to use in requests from that data source to a service. For example, if you create an access policy specific for reading logs, then you will need to create a token for that policy that can be added to your Loki configuration.

You can create an access policy token using the Grafana Cloud API or using the Cloud Access Policies Plugin. Access policies created using the plugin are tied to the stack where they are created.

Note: Any token you create is only shown once. Copy and save it in a safe place, like a secure note, password app, or other protected location. If you lose a token, you will need to generate a new one and update any configurations where that token was used.

To use the API, refer to the Create a token section of the Grafana Cloud API documentation.

To create a token using the Cloud Access Policies Plugin:

  1. Sign in to Grafana Cloud and start the stack where you wish to create the access policy.
  2. Select the Configuration (gear) icon in the left navigation to open the Configuration screen.
  3. Click the Cloud access policies tab, then select an access policy.
  4. Select Add token to display the Create new token dialog.
    Create a new token dialog
    Create a new token dialog
  5. Enter a Display name for the token.
  6. Enter an Expiration date in month/day/year format. Leave the field blank to prevent the token from expiring.
  7. Select Create to generate the token.
    The available scopes in the Cloud Access Policies plugin.
    The available scopes in the Cloud Access Policies plugin.
  8. Select Copy to clipboard to copy the generated token.

Next, either add the token to your data source’s or agent’s configuration or save the token in a secure location like a password app so you can refer to it later.

Add the token to your agent’s or Grafana data source’s configuration

The token you created needs to be added to the agent’s or Grafana data source’s configuration to allow agents to include the token with any request sent to Grafana Cloud. If the API request does an action that is allowed by an access policy (identified by the token), then the API request will be authorized.

These tokens will either be used with a data source in Grafana Cloud or with the tool that you use to send data to Grafana–most likely the Grafana Agent.

Grafana Cloud supports many integrations and data sources. The exact steps for adding the token to each integration and data source may vary. In general, agent or service configurations that reference a password or API key can be replaced with the token.

Note: Tokens do not replace user account passwords.

This procedure provides the approximate steps to create a data source using a Grafana Cloud token:

  1. Copy the token for the service you are selecting.
  2. In Grafana, select Configuration in the left navigation.
  3. Choose the data source you wish to update or add.
  4. Update the Basic Auth details for your data source. For example, if you are using Loki, then the User is the log tenant ID and the password is the token.
  5. Select Save & test to verify the configuration.

For more detailed instructions, please refer to the integration documentation:

Note: You can see specific configuration instructions for creating data sources based on Grafana Cloud Prometheus, Loki, Graphite, Tempo, or Alertmanager by signing into your Grafana Cloud account, choosing a stack, and selecting the given service.

Modify an access policy

Access policies can be modified after they are created using the Cloud Access Policy API or the Cloud Access Policies Plugin. The plugin can only be used to modify policies associated with a specific stack.

To use the API, refer to the Access Policies endpoint section of the Grafana Cloud API documentation.

To modify an access policy using the Cloud Access Policies Plugin:

  1. Sign in to Grafana Cloud and start the stack where you wish to create the access policy.
  2. Select the Configuration (gear) icon in the left navigation to open the Configuration screen.
  3. Click the Cloud access policies tab.
  4. Locate and select the access policy you wish to modify.
  5. Modify the policy as desired and select Update to save the changes.

Delete an access policy token

Once a token has been created, it can not be modified. Removing the token prevents it from being used with any defined access policies.

For API instructions, refer to the Delete a token section of the Grafana Cloud API documentation.

To delete a token using the Cloud Access Policies Plugin:

  1. Sign in to Grafana Cloud and start the stack where you wish to create the access policy.
  2. Select the Configuration (gear) icon in the left navigation to open the Configuration screen.
  3. Click the Cloud access policies tab.
  4. Locate the policy associated with the token you wish to remove.
  5. Select the trash can icon to the right side to remove the token.
  6. Confirm the removal by selecting Delete on the Delete token dialog.

Delete an access policy

Access policies can be modified or deleted using the Cloud Access Policies API or the Cloud Access Policies plugin. Deleting an access policy removes all tokens associated with it. There may be a few minutes delay to apply everywhere.

To use the API, refer to the Access Policies endpoint section of the Grafana Cloud API documentation.

To delete an access policy for the selected stack using the Grafana Cloud Access Policies Plugin:

  1. Sign in to Grafana Cloud and start the stack where you wish to create the access policy.
  2. Select the Configuration (gear) icon in the left navigation to open the Configuration screen.
  3. Click the Cloud access policies tab.
  4. Locate the access policy you wish to remove.
  5. Select the trash can icon to the right side to remove the policy.
  6. Confirm the removal by selecting Delete on the dialog.