Skip to main content

​
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 -X GET http://localhost:3000/api/user \
  -u admin:admin
​
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 -X GET http://localhost:3000/api/users/1 \
  -u admin:admin
​
user_id
integer
required
User ID

​
Get User by Login or Email

Lookup a user by login name or email address. 
curl -X GET "http://localhost:3000/api/users/lookup?loginOrEmail=admin@localhost" \
  -u admin:admin
​
loginOrEmail
string
required
Username or email address to lookup

​
Update Current User

Update the current user’s profile. 
curl -X PUT http://localhost:3000/api/user \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "name": "Administrator",
    "login": "admin",
    "theme": "light"
  }'
​
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 -X PUT http://localhost:3000/api/users/1 \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "User Name",
    "login": "username"
  }'
​
user_id
integer
required
User ID

​
Change Password

Change the current user’s password. 
curl -X PUT http://localhost:3000/api/user/password \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "oldPassword": "admin",
    "newPassword": "newSecurePassword123",
    "confirmNew": "newSecurePassword123"
  }'
​
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 -X GET http://localhost:3000/api/users/1/orgs \
  -u admin:admin
​
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 -X GET http://localhost:3000/api/user/orgs \
  -u admin:admin

​
Get User Teams

Get all teams for a specific user. 
curl -X GET http://localhost:3000/api/users/1/teams \
  -u admin:admin
​
user_id
integer
required
User ID

​
Switch User Organization

Switch the current user’s active organization. 
curl -X POST http://localhost:3000/api/user/using/2 \
  -u admin:admin
​
org_id
integer
required
Organization ID to switch to

​
Search Users

Search for users (deprecated - use search with paging instead). 
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 -X GET "http://localhost:3000/api/users/search?perpage=10&page=1&query=admin" \
  -u admin:admin
​
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>