Users API

Manage users and user profiles

Users API

The Users API provides endpoints for managing Grafana users and their profiles.

Get Current User

Get profile information for the currently authenticated user.

cURL

curl -X GET http://localhost:3000/api/user \
  -u admin:admin

{
  "id": 1,
  "uid": "u000000001",
  "email": "admin@localhost",
  "name": "Admin",
  "login": "admin",
  "theme": "dark",
  "orgId": 1,
  "isGrafanaAdmin": true,
  "isDisabled": false,
  "isExternal": false,
  "authLabels": [],
  "updatedAt": "2021-06-01T12:00:00Z",
  "createdAt": "2021-01-01T10:00:00Z",
  "avatarUrl": "/avatar/abc123"
}

id · integer

User internal ID

uid · string

User unique identifier

email · string

User email address

login · string

Username

name · string

Display name

isGrafanaAdmin · boolean

Whether user has Grafana admin privileges

Get User by ID

Retrieve user information by user ID.

cURL

curl -X GET http://localhost:3000/api/users/1 \
  -u admin:admin

{
  "id": 1,
  "uid": "u000000001",
  "email": "admin@localhost",
  "name": "Admin",
  "login": "admin",
  "theme": "dark",
  "orgId": 1,
  "isGrafanaAdmin": true,
  "isDisabled": false
}

user_id · integer · required

User ID

Get User by Login or Email

Lookup a user by login name or email address.

cURL

curl -X GET "http://localhost:3000/api/users/lookup?loginOrEmail=admin@localhost" \
  -u admin:admin

{
  "id": 1,
  "uid": "u000000001",
  "email": "admin@localhost",
  "name": "Admin",
  "login": "admin",
  "theme": "dark",
  "isGrafanaAdmin": true
}

loginOrEmail · string · required

Username or email address to lookup

Update Current User

Update the current user’s profile.

cURL

curl -X PUT http://localhost:3000/api/user \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "name": "Administrator",
    "login": "admin",
    "theme": "light"
  }'

{
  "message": "User updated"
}

email · string

Email address

name · string

Display name

login · string

Username

theme · string

UI theme: “light” or “dark”

Update User

Update a user by their ID (admin only).

cURL

curl -X PUT http://localhost:3000/api/users/1 \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "name": "User Name",
    "login": "username"
  }'

{
  "message": "User updated"
}

user_id · integer · required

User ID

Change Password

Change the current user’s password.

cURL

curl -X PUT http://localhost:3000/api/user/password \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "oldPassword": "admin",
    "newPassword": "newSecurePassword123",
    "confirmNew": "newSecurePassword123"
  }'

{
  "message": "User password changed"
}

oldPassword · string · required

Current password

newPassword · string · required

New password

confirmNew · string · required

Confirm new password

Get User Organizations

Get all organizations for a specific user.

cURL

curl -X GET http://localhost:3000/api/users/1/orgs \
  -u admin:admin

[
  {
    "orgId": 1,
    "name": "Main Org.",
    "role": "Admin"
  },
  {
    "orgId": 2,
    "name": "Second Org.",
    "role": "Editor"
  }
]

user_id · integer · required

User ID

orgId · integer

Organization ID

name · string

Organization name

role · string

User’s role in the organization: “Admin”, “Editor”, or “Viewer”

Get Current User Organizations

Get organizations for the currently authenticated user.

cURL

curl -X GET http://localhost:3000/api/user/orgs \
  -u admin:admin

Get User Teams

Get all teams for a specific user.

cURL

curl -X GET http://localhost:3000/api/users/1/teams \
  -u admin:admin

[
  {
    "id": 1,
    "orgId": 1,
    "name": "Engineering",
    "email": "[e-mail]",
    "memberCount": 5
  }
]

user_id · integer · required

User ID

Switch User Organization

Switch the current user’s active organization.

cURL

curl -X POST http://localhost:3000/api/user/using/2 \
  -u admin:admin

{
  "message": "Active organization changed"
}

org_id · integer · required

Organization ID to switch to

Search Users

Search for users (deprecated - use search with paging instead).

cURL

curl -X GET "http://localhost:3000/api/users?perpage=10&page=1" \
  -u admin:admin

perpage · integer · default: "1000"

Number of users per page

page · integer · default: "1"

Page number

Search Users with Paging

Search for users with pagination support.

cURL

curl -X GET "http://localhost:3000/api/users/search?perpage=10&page=1&query=admin" \
  -u admin:admin

{
  "totalCount": 1,
  "users": [
    {
      "id": 1,
      "uid": "u000000001",
      "name": "Admin",
      "login": "admin",
      "email": "admin@localhost",
      "isAdmin": true
    }
  ],
  "page": 1,
  "perPage": 10
}

query · string

Search query (searches name, login, and email fields)

perpage · integer · default: "1000"

Number of users per page

page · integer · default: "1"

Page number

Permissions

If you are running Grafana Enterprise with Fine-grained access control enabled:

• Read user: Requires users:read permission
• Update user: Requires users:write permission with scope users:id:<id>
• Create user: Requires users:create permission
• Delete user: Requires users:delete permission with scope users:id:<id>