DocumentationGrafana CloudAccount managementAuthorization and permissionsGrafana Cloud Access PoliciesAuthorize your service with an access policy and token

Authorize your service with an access policy and token

You can manage Grafana Cloud Access Policies using the API, the Access Policies page in the Cloud Portal, or the Grafana Administration settings.

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 or Grafana data source configuration file

For an introduction to Grafana Cloud Access Policies, read the November 22, 2022, blog post by Ryan Melendez, “Grafana Cloud Access Policies: Say hi to the new Cloud API keys.”

Before you begin

• To manage access policies from the Grafana Administration settings, you must have the Admin role within that Grafana. However, to manage access policies in the Cloud Portal, you must have the Admin role within the Cloud Portal. These roles are set independently.

Create an access policy

Following the principle of least privilege, an access policy should only have the necessary scopes. Consider whether the access policy needs to apply to only one stack or across multiple stacks within an organization. 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.

If the access policies need to apply to multiple stacks within an organization, then the access policy (or policies) and tokens can be created in the Access Policies page in the Cloud Portal. If the access policies and tokens only apply to one stack, then you can configure access policies within that stack’s Grafana.

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

Create an access policy for a stack

To create an access policy using Cloud access policies:

1. Sign in to Grafana Cloud and start the stack where you wish to create the access policy.

2. Click Administration in the left-side menu and select Cloud access policies.

3. Click 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. Not all scopes are displayed by default. If you do not see the scope that you are looking for, (for example, stack:read) use the Add scope drop-down towards the bottom of the dialog, and select the scope you would like to configure.

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. Add IP ranges, if desired.

   For more information, refer to Using IP range based access control with access policies.

9. Select Create to add the access policy.

Create an access policy for an organization

Organization-level access policies apply to all stacks within an organization unless you select specific stacks in the Realm field. To create an access policy using the organization’s Access Policies page:

1. Sign in to Grafana Cloud.

2. Select an organization in the drop-down at the top of the page.

3. Locate Security in the left-hand navigation and select Access Policies.

4. Select Create access policy.

5. Enter a Display Name for the access policy.

6. Optional: Update the Name field. This field is automatically populated with the Display name.

7. Optional: Select one or more stacks from the Realm drop-down. If no stack is selected, then the access policy applies across the organization.

8. Select one or more scopes for the policy.

9. 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.

10. Add IP ranges, if desired.

    For more information, refer to Using IP range based access control with access policies.

11. Select Create to add the access policy.

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.

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

To create a token for an access policy:

1. Sign in to Grafana Cloud.
2. Navigate to the access policies page.
   1. From within a Grafana Stack: Click Administration and select Cloud access policies.
   2. Using the Cloud Portal: Select your organization, then under Security, select Access Policies.
3. Choose an access policy.
4. Select Add token to display the Create new token dialog.
   

5. Enter a Display name for the token.
6. Optional: Enter an Expiration date in year/month/day format. Leave the field blank to prevent the token from expiring.
7. Select Create to generate the token.
   

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 or Grafana data source configuration

The token you created needs to be added to the agent or Grafana data source 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.

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 Connections in the left-side menu.

3. Filter for the data source you wish to update or add.

   When you add a data source, you’ll be taken to the configuration page for it.

4. On the Settings tab, 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:

• Alertmanager
• Graphite
• Loki
• Prometheus
• Tempo

Modify an access policy

You can change an access policy created within a stack using the Access Policy page in the Cloud Portal. However, an access policy created in the Cloud Portal and applied to a stack can not be modified using the Cloud access policies from within the stack; the policy has to be changed at the Access Policies page.

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

To modify an access policy:

1. Sign in to Grafana Cloud.
2. Navigate to the access policies page.
   • From within a Grafana Stack: Click Administration and select Cloud access policies.
   • Using the Cloud Portal: Select your organization, then under Security, select Access Policies.
3. Locate and select the access policy you wish to modify.
4. 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:

1. Sign in to Grafana Cloud.
2. Navigate to the access policies page.
   • From within a Grafana Stack: Click Administration and select Cloud access policies.
   • Using the Cloud Portal: Select your organization, then under Security, select Access Policies.
3. Locate the access policy associated with the token you wish to remove.
4. Select the trash can icon to the right side to remove the token.
5. Confirm the removal by selecting Delete on the Delete token dialog.

Delete an access policy

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:

1. Sign in to Grafana Cloud.
2. Navigate to the access policies page.
   • From within a Grafana Stack: Click Administration and select Cloud access policies.
   • Using the Cloud Portal: Select your organization, then under Security, select Access Policies.
3. Locate the access policy you wish to remove.
4. Select the trash can icon to the right side to remove the policy.
5. Confirm the removal by selecting Delete on the dialog.