openapi: 3.0.3
info:
title: Grafana HTTP Access Users API
description: The Grafana HTTP API provides programmatic access to Grafana's core functionality including dashboards, data sources, alerts, users, organizations, folders, annotations, and teams. Authentication is handled via API keys, basic auth, or OAuth tokens passed in the Authorization header.
version: 11.0.0
contact:
name: Grafana Labs
url: https://grafana.com
license:
name: AGPL-3.0
url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: https://{instance}.grafana.net/api
description: Grafana Cloud
variables:
instance:
default: your-instance
- url: http://localhost:3000/api
description: Local Grafana instance
security:
- BearerAuth: []
- BasicAuth: []
- ApiKeyAuth: []
tags:
- name: Users
description: User management
paths:
/admin/users:
parameters: []
post:
tags:
- Users
operationId: adminCreateUser
summary: Create a new user (admin)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserCommand'
responses:
'200':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserResponse'
/users:
parameters: []
get:
tags:
- Users
operationId: searchUsers
summary: Search users
parameters:
- name: perpage
in: query
schema:
type: integer
default: 1000
- name: page
in: query
schema:
type: integer
default: 1
- name: query
in: query
schema:
type: string
responses:
'200':
description: Users found
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserSearchHit'
/users/{id}:
get:
tags:
- Users
operationId: getUserById
summary: Get user by ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: User found
content:
application/json:
schema:
$ref: '#/components/schemas/User'
put:
tags:
- Users
operationId: updateUser
summary: Update user
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserCommand'
responses:
'200':
description: User updated
/user:
parameters: []
get:
tags:
- Users
operationId: getCurrentUser
summary: Get current user
responses:
'200':
description: Current user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
put:
tags:
- Users
summary: Grafana Update Signed In User
description: Updates the profile information for the currently authenticated user in Grafana, allowing modification of fields such as email address, name, login username, and theme preferences. This endpoint requires the user to be signed in and operates on the user's own account, making it a self-service operation for managing personal account details. The request accepts a JSON payload containing the user attributes to be updated, and upon successful execution, returns the updated user information along with a confirmation message.
operationId: updateSignedInUser
parameters: []
requestBody:
description: To change the email, name, login, theme, provide another one.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/UpdateUserCommand_2'
- description: To change the email, name, login, theme, provide another one.
contentMediaType: application/json
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'409':
description: ConflictError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/orgs/{org_id}/users:
parameters: []
get:
tags:
- Users
summary: Grafana Get Org Users
description: Retrieves a list of all users that belong to a specific organization in Grafana by providing the organization ID in the URL path. This GET endpoint returns user details including their names, email addresses, roles, and permissions within the specified organization, allowing administrators to view and manage organization membership and access control.
operationId: getOrgUsers
parameters:
- name: org_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OrgUserDTO'
description: ''
contentMediaType: application/json
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
security:
- basic: []
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
post:
tags:
- Users
summary: Grafana Add Org User
description: Adds a new user to an existing organization in Grafana by sending a POST request to the /orgs/{org_id}/users endpoint, where {org_id} is the unique identifier of the target organization. This operation requires authentication and appropriate permissions to manage organization membership. The request body typically includes the user's login credentials or user ID along with the desired role (such as Viewer, Editor, or Admin) that determines their access level within the organization. Upon successful execution, the specified user becomes a member of the organization with the assigned role and can access resources and dashboards according to their permission level.
operationId: addOrgUser
parameters:
- name: org_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AddOrgUserCommand'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/orgs/{org_id}/users/search:
parameters: []
get:
tags:
- Users
summary: Grafana Search Org Users
description: This API operation allows you to search for users within a specific organization in Grafana by providing the organization ID in the URL path. It uses the GET HTTP method to retrieve a filtered list of users belonging to the specified organization, enabling administrators to query and find specific users based on search criteria. The endpoint is useful for managing organization membership and performing user lookups within the context of a particular Grafana organization.
operationId: searchOrgUsers
parameters:
- name: org_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SearchOrgUsersQueryResult'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
security:
- basic: []
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/orgs/{org_id}/users/{user_id}:
parameters: []
delete:
tags:
- Users
summary: Grafana Remove Org User
description: This API operation removes a specific user from a designated organization in Grafana by sending a DELETE request to the endpoint /orgs/{org_id}/users/{user_id}, where org_id represents the unique identifier of the organization and user_id represents the unique identifier of the user to be removed. When executed successfully, this operation revokes the user's membership and access rights within the specified organization, effectively disconnecting them from that particular organizational context while potentially maintaining their user account in the Grafana instance for participation in other organizations or contexts.
operationId: removeOrgUser
parameters:
- name: org_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
- name: user_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
patch:
tags:
- Users
summary: Grafana Update Org User
description: This API operation updates an existing user's role within a specific organization in Grafana. It uses a PATCH request to the endpoint /orgs/{org_id}/users/{user_id}, where org_id identifies the target organization and user_id specifies which user's permissions should be modified. The operation allows administrators to change a user's role (such as Viewer, Editor, or Admin) within the organization context, enabling granular control over user permissions and access levels across different Grafana organizations.
operationId: updateOrgUser
parameters:
- name: org_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
- name: user_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateOrgUserCommand'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/org/users:
parameters: []
get:
tags:
- Users
summary: Grafana Get Org Users For Current Org
description: This API operation retrieves a list of all users who belong to the currently authenticated organization in Grafana. When called, it returns user information for members of the organization context associated with the API request, including details such as user IDs, email addresses, login names, roles within the organization, and authentication information. This is useful for administrators who need to audit organization membership, manage user access, or integrate Grafana's user management with external systems. The operation requires appropriate permissions within the current organization context to execute successfully.
operationId: getOrgUsersForCurrentOrg
parameters:
- name: query
in: query
description: ''
style: form
explode: true
schema:
type: string
- name: limit
in: query
description: ''
style: form
explode: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OrgUserDTO'
description: ''
contentMediaType: application/json
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
post:
tags:
- Users
summary: Grafana Add Org User To Current Org
description: This API operation allows administrators to add a new user to the current organization in Grafana by sending a POST request to the /org/users endpoint. When invoked, it creates a new membership association between a specified user and the organization that the authenticated user currently belongs to. The request typically requires parameters such as the user's login credentials or user ID, along with the desired role (Viewer, Editor, or Admin) that the new member should have within the organization. This operation requires appropriate administrative permissions and is commonly used when onboarding team members or managing organizational access control in Grafana instances.
operationId: addOrgUserToCurrentOrg
parameters: []
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AddOrgUserCommand'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/org/users/lookup:
parameters: []
get:
tags:
- Users
summary: Grafana Get Org Users For Current Org Lookup
description: This API operation retrieves user information for members of the current organization in Grafana by performing a lookup query. It uses a GET request to the '/org/users/lookup' endpoint and returns details about users belonging to the organization context of the authenticated request. This is typically used when you need to search for or validate specific users within your current Grafana organization without iterating through the entire user list, providing a more efficient way to find user data based on lookup criteria such as login name or email address.
operationId: getOrgUsersForCurrentOrgLookup
parameters:
- name: query
in: query
description: ''
style: form
explode: true
schema:
type: string
- name: limit
in: query
description: ''
style: form
explode: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserLookupDTO'
description: ''
contentMediaType: application/json
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/org/users/{user_id}:
parameters: []
delete:
tags:
- Users
summary: Grafana Remove Org User For Current Org
description: This API operation removes a specified user from the current organization in Grafana by making a DELETE request to the endpoint /org/users/{user_id}, where {user_id} is the unique identifier of the user to be removed. When executed, it disassociates the targeted user from the organization context in which the API call is made, effectively revoking their access and permissions within that specific organization. This operation requires appropriate administrative privileges within the current organization and only affects the user's membership in that particular organization, not their overall Grafana account or memberships in other organizations they may belong to.
operationId: removeOrgUserForCurrentOrg
parameters:
- name: user_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
patch:
tags:
- Users
summary: Grafana Update Org User For Current Org
description: This API operation allows you to update an existing organization user's details within the currently authenticated organization in Grafana. By sending a PATCH request to the endpoint with a specific user ID, you can modify properties such as the user's role within the organization without affecting their underlying Grafana user account. This is particularly useful for managing permissions and access levels of team members, allowing administrators to promote users to admin roles or adjust their organizational privileges while maintaining their user identity across multiple organizations they may belong to.
operationId: updateOrgUserForCurrentOrg
parameters:
- name: user_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateOrgUserCommand'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/access-control/users/roles/search:
parameters: []
post:
tags:
- Users
summary: Grafana List Users Roles
description: This API operation allows you to search and retrieve a list of roles assigned to users within Grafana's access control system. By sending a POST request to the /access-control/users/roles/search endpoint, you can query and filter user role assignments based on various criteria. The operation is useful for administrators who need to audit user permissions, manage access control policies, or retrieve information about which roles are assigned to specific users across the Grafana instance. The POST method enables you to include search parameters in the request body to narrow down results based on your specific requirements.
operationId: listUsersRoles
parameters: []
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/RolesSearchQuery'
required: true
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: object
additionalProperties:
type: object
contentMediaType: application/json
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalSe
# --- truncated at 32 KB (133 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grafana/refs/heads/main/openapi/grafana-users-api-openapi.yml