Grafana Cloud Admin

Docs: https://grafana.com/docs/grafana-cloud/account-management.md

Common Workflows

Setting up a new stack

# 1. Create the stack via Cloud API
curl -X POST https://grafana.com/api/instances \
  -H "Authorization: Bearer <grafana-com-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-new-stack", "slug": "my-new-stack", "region": "us-east-0", "plan": "grafana-cloud-free"}'

# 2. Verify the stack is reachable (poll until 200)
until curl -fs https://my-new-stack.grafana.net/api/health > /dev/null; do sleep 2; done

# 3. Mint an admin service-account token (see § Service Accounts below)

# 4. Test the token
curl https://my-new-stack.grafana.net/api/org -H "Authorization: Bearer <token>"
# Returns 200 + org JSON → token works

Onboarding a team

1. Invite users via POST /api/org/invites (one curl per user — see references/api-reference.md § Stack API)
2. Create the team via POST /api/teams
3. Add each user via POST /api/teams/{teamId}/members
4. Assign an RBAC role to the team (see § RBAC below)
5. Verify: GET /api/teams/{teamId}/members returns the expected user list

Configuring SSO (Okta / SAML / GitHub)

1. Pick the provider config from references/sso.md and drop into grafana.ini
2. Restart Grafana
3. Always validate in an incognito window before announcing: see references/sso.md § Verifying SSO for the 5-step verification + role-mapping debug pattern

Deleting a stack (destructive)

# 1. Delete via Cloud API
curl -X DELETE https://grafana.com/api/instances/{id} \
  -H "Authorization: Bearer <grafana-com-api-key>"

# 2. Verify the stack is gone (must return 404)
curl https://grafana.com/api/instances/{id} \
  -H "Authorization: Bearer <grafana-com-api-key>"

If the GET still returns 200 after a few seconds, the delete didn't apply — re-check the stack ID and Cloud API key.

Organization and Stack Structure

Grafana Cloud Account
└── Organization (billing unit)
    ├── Stack 1 (prod)   → dedicated Grafana, Prometheus, Loki, Tempo URLs
    ├── Stack 2 (staging)
    └── Stack 3 (dev)

• Organization: top-level account with billing, users, API keys, stacks
• Stack: dedicated Grafana + LGTM instance with its own URLs and credentials

User Roles

RBAC

Define a custom role + assignment in provisioning YAML:

# provisioning/access-control/roles.yaml
apiVersion: 1
roles:
  - name: TeamDashboardEditor
    description: Edit dashboards within team folder
    permissions:
      - action: dashboards:read
        scope: folders:UID:team-folder
      - action: dashboards:write
        scope: folders:UID:team-folder
      - action: dashboards:create
        scope: folders:UID:team-folder

# provisioning/access-control/assignments.yaml
apiVersion: 1
roleAssignments:
  - roleName: TeamDashboardEditor
    users:
      - alice@example.com
      - bob@example.com
    teams:
      - platform-team

After committing the YAML and restarting Grafana, verify the role applied: GET /api/access-control/roles | jq '.[] | select(.name=="TeamDashboardEditor")'.

Service Accounts

Service accounts are the recommended way for programmatic access (CI/CD, Terraform, agents).

# 1. Create the service account
curl -X POST https://yourstack.grafana.net/api/serviceaccounts \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "terraform-provisioner", "role": "Admin", "isDisabled": false}'

# 2. Mint a token for it
curl -X POST https://yourstack.grafana.net/api/serviceaccounts/{id}/tokens \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-token", "secondsToLive": 0}'

# 3. Verify the token works (test on a harmless endpoint)
curl https://yourstack.grafana.net/api/org \
  -H "Authorization: Bearer <new-token>"
# 200 + org JSON → token works. Anything else → re-check role assignment in step 1.

Provisioning equivalent (YAML, declarative):

# provisioning/access-control/service_accounts.yaml
apiVersion: 1
serviceAccounts:
  - name: alloy-writer
    orgId: 1
    role: Editor
    tokens:
      - name: alloy-token

References

• references/sso.md — OAuth / SAML / GitHub OAuth config + the 5-step SSO verification pattern + common failure modes
• references/terraform.md — Terraform provider config + common resource patterns (teams, users, folders, dashboards) + drift troubleshooting
• references/api-reference.md — full Cloud API + Stack API endpoint reference + audit-log queries