Users & Teams API Reference

Users & Teams API Reference

Complete reference for Grafana User, Team, and Service Account HTTP API endpoints.

Table of Contents

• Current User
• Users (Admin)
• Teams
• Team Members
• Service Accounts
• Service Account Tokens
• Organizations
• Organization Users

Current User

Get Current User

GET /api/user

Example Response:

{
  "id": 1,
  "email": "admin@example.com",
  "name": "Admin User",
  "login": "admin",
  "theme": "dark",
  "orgId": 1,
  "isGrafanaAdmin": true,
  "isDisabled": false,
  "isExternal": false,
  "authLabels": [],
  "updatedAt": "2024-06-20T14:22:00Z",
  "createdAt": "2023-01-15T10:30:00Z",
  "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
}

Update Current User

PUT /api/user

{
  "name": "New Name",
  "email": "newemail@example.com",
  "login": "newlogin",
  "theme": "light"
}

Get Current User Organizations

GET /api/user/orgs

Get Current User Teams

GET /api/user/teams

Star/Unstar Dashboard

POST /api/user/stars/dashboard/uid/:dashboardUID
DELETE /api/user/stars/dashboard/uid/:dashboardUID

Change Active Organization

POST /api/user/using/:orgId

Users (Admin)

Requires Grafana Admin permission.

Search Users

GET /api/users/search

Query Parameters:

Example Response:

{
  "totalCount": 2,
  "users": [
    {
      "id": 1,
      "name": "Admin User",
      "login": "admin",
      "email": "admin@example.com",
      "isAdmin": true,
      "isDisabled": false,
      "lastSeenAt": "2024-06-20T14:22:00Z",
      "lastSeenAtAge": "2m",
      "authLabels": ["OAuth"]
    }
  ],
  "page": 1,
  "perPage": 10
}

Get User by ID

GET /api/users/:id

Create User

POST /api/admin/users

{
  "name": "New User",
  "email": "newuser@example.com",
  "login": "newuser",
  "password": "password123",
  "OrgId": 1
}

Update User

PUT /api/users/:id

{
  "name": "Updated Name",
  "email": "updated@example.com",
  "login": "updatedlogin",
  "theme": "dark"
}

Delete User

DELETE /api/admin/users/:id

Update User Permissions

PUT /api/admin/users/:id/permissions

{
  "isGrafanaAdmin": true
}

Disable/Enable User

POST /api/admin/users/:id/disable
POST /api/admin/users/:id/enable

Teams

Search Teams

GET /api/teams/search

Query Parameters:

Example Response:

{
  "totalCount": 1,
  "teams": [
    {
      "id": 1,
      "orgId": 1,
      "name": "Platform Team",
      "email": "platform@example.com",
      "avatarUrl": "/avatar/3f49c15916554246daa714b9bd0ee398",
      "memberCount": 5,
      "permission": 0
    }
  ],
  "page": 1,
  "perPage": 1000
}

Get Team by ID

GET /api/teams/:teamId

Create Team

POST /api/teams

{
  "name": "DevOps Team",
  "email": "devops@example.com"
}

Update Team

PUT /api/teams/:teamId

{
  "name": "Updated Team Name",
  "email": "newemail@example.com"
}

Delete Team

DELETE /api/teams/:teamId

Team Members

Get Team Members

GET /api/teams/:teamId/members

Example Response:

[
  {
    "orgId": 1,
    "teamId": 1,
    "userId": 2,
    "email": "user@example.com",
    "name": "User Name",
    "login": "username",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
    "labels": [],
    "permission": 0
  }
]

Add Team Member

POST /api/teams/:teamId/members

{
  "userId": 5
}

Remove Team Member

DELETE /api/teams/:teamId/members/:userId

Update Team Member Permission

PUT /api/teams/:teamId/members/:userId

{
  "permission": 4
}

Permission Values:

• 0: Member
• 4: Admin

Service Accounts

Search Service Accounts

GET /api/serviceaccounts/search

Query Parameters:

Example Response:

{
  "totalCount": 1,
  "serviceAccounts": [
    {
      "id": 1,
      "name": "automation-sa",
      "login": "sa-automation-sa",
      "orgId": 1,
      "isDisabled": false,
      "role": "Editor",
      "tokens": 2,
      "avatarUrl": "/avatar/85ec38023d90823d3e5b43ef35646af9"
    }
  ],
  "page": 1,
  "perPage": 10
}

Get Service Account by ID

GET /api/serviceaccounts/:id

Create Service Account

POST /api/serviceaccounts

{
  "name": "automation-sa",
  "role": "Editor",
  "isDisabled": false
}

Roles: Viewer, Editor, Admin

Update Service Account

PATCH /api/serviceaccounts/:id

{
  "name": "new-name",
  "role": "Admin",
  "isDisabled": false
}

Delete Service Account

DELETE /api/serviceaccounts/:id

Service Account Tokens

List Tokens

GET /api/serviceaccounts/:id/tokens

Example Response:

[
  {
    "id": 1,
    "name": "token-1",
    "created": "2024-06-20T14:22:00Z",
    "expiration": "2024-12-20T14:22:00Z",
    "secondsUntilExpiration": 15552000,
    "hasExpired": false,
    "lastUsedAt": "2024-06-20T14:22:00Z"
  }
]

Create Token

POST /api/serviceaccounts/:id/tokens

{
  "name": "automation-token",
  "secondsToLive": 86400
}

Use secondsToLive: 0 for non-expiring tokens.

Response:

{
  "id": 2,
  "name": "automation-token",
  "key": "glsa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Important: The key is only shown once. Store it securely.

Delete Token

DELETE /api/serviceaccounts/:id/tokens/:tokenId

Organizations

Get Current Organization

GET /api/org

Update Current Organization

PUT /api/org

{
  "name": "New Org Name"
}

List Organizations (Admin)

GET /api/orgs

Create Organization (Admin)

POST /api/orgs

{
  "name": "New Organization"
}

Get Organization by ID (Admin)

GET /api/orgs/:orgId

Update Organization (Admin)

PUT /api/orgs/:orgId

Delete Organization (Admin)

DELETE /api/orgs/:orgId

Organization Users

Get Current Org Users

GET /api/org/users

Example Response:

[
  {
    "orgId": 1,
    "userId": 1,
    "email": "admin@example.com",
    "name": "Admin",
    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
    "login": "admin",
    "role": "Admin",
    "lastSeenAt": "2024-06-20T14:22:00Z",
    "lastSeenAtAge": "2m"
  }
]

Add User to Current Org

POST /api/org/users

{
  "loginOrEmail": "user@example.com",
  "role": "Viewer"
}

Update User Role in Current Org

PATCH /api/org/users/:userId

{
  "role": "Editor"
}

Remove User from Current Org

DELETE /api/org/users/:userId

Get Org Users (Admin)

GET /api/orgs/:orgId/users

Add User to Org (Admin)

POST /api/orgs/:orgId/users

{
  "loginOrEmail": "user@example.com",
  "role": "Viewer"
}

Update User Role in Org (Admin)

PATCH /api/orgs/:orgId/users/:userId

Remove User from Org (Admin)

DELETE /api/orgs/:orgId/users/:userId