Grafana Role API

openapi: 3.0.3
info:
  title: Grafana HTTP Access Role 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: Role
paths:
  /access-control/roles:
    parameters: []
    post:
      tags:
      - Role
      summary: Grafana Create Role
      description: Creates a new custom role in Grafana's role-based access control (RBAC) system. This endpoint allows administrators to define granular permissions by creating roles with specific sets of permissions that can be assigned to users, teams, or service accounts. The request requires specifying the role name, display name, description, and optionally a set of permissions that define what actions the role can perform within Grafana. Custom roles enable organizations to implement fine-grained access control policies beyond the built-in roles, allowing them to tailor permissions to match their specific security and operational requirements. Upon successful creation, the API returns the newly created role object including its unique identifier and assigned permissions.
      operationId: createRole
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleForm'
        required: true
      responses:
        '201':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleDTO'
        '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: 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/roles/{roleUID}:
    parameters: []
    get:
      tags:
      - Role
      summary: Grafana Get Role
      description: This API operation retrieves detailed information about a specific role in Grafana's access control system by providing the role's unique identifier (roleUID) in the URL path. When called with a GET request, it returns the complete role definition including the role's name, description, version, permissions, and any other associated metadata. This endpoint is useful for administrators who need to inspect role configurations, audit permissions, or retrieve role details before performing updates or modifications to the access control system.
      operationId: getRole
      parameters:
      - name: roleUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleDTO'
        '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
    put:
      tags:
      - Role
      summary: Grafana Update Role
      description: This API operation updates an existing role in Grafana's access control system by sending a PUT request to the endpoint with the role's unique identifier (roleUID) in the path. It allows administrators to modify role properties such as the role name, description, permissions, and other attributes associated with that specific role. The request requires the roleUID parameter to identify which role to update, and the request body contains the updated role configuration. This operation is typically used for managing custom roles and adjusting access permissions within Grafana's role-based access control (RBAC) system, enabling fine-grained control over user capabilities and resource access.
      operationId: updateRole
      parameters:
      - name: roleUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleCommand'
        required: true
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleDTO'
        '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'
        '404':
          description: NotFoundError is returned when the requested resource was not found.
          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
    delete:
      tags:
      - Role
      summary: Grafana Delete Role
      description: Removes a custom role from Grafana's access control system by specifying its unique identifier (roleUID). This operation permanently deletes the role definition along with all its associated permissions and assignments to users or teams. Only custom roles can be deleted through this endpoint, as built-in system roles are protected from deletion. The operation requires appropriate administrative permissions and will fail if the specified roleUID does not exist or references a non-deletable system role. Once deleted, any users or teams previously assigned this role will lose the associated permissions immediately.
      operationId: deleteRole
      parameters:
      - name: force
        in: query
        description: ''
        style: form
        explode: true
        schema:
          type: boolean
      - name: global
        in: query
        description: ''
        style: form
        explode: true
        schema:
          type: boolean
      - name: roleUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      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'
        '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/roles/{roleUID}/assignments:
    parameters: []
    get:
      tags:
      - Role
      summary: Grafana Get Role Assignments
      description: This API operation retrieves all current assignments for a specific role in Grafana's access control system by providing the role's unique identifier (roleUID) in the endpoint path. When called with a GET request, it returns a list of users, teams, or service accounts that have been assigned the specified role, allowing administrators to audit and review who has been granted particular permissions within their Grafana instance. This is useful for security audits, compliance checks, and understanding the current permission distribution across the organization's Grafana environment.
      operationId: getRoleAssignments
      parameters:
      - name: roleUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleAssignmentsDTO'
        '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'
        '404':
          description: NotFoundError is returned when the requested resource was not found.
          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
    put:
      tags:
      - Role
      summary: Grafana Set Role Assignments
      description: Updates the complete set of role assignments for a specific role identified by its UID in Grafana's access control system. This operation replaces all existing assignments with the new set provided in the request body, allowing administrators to define which users, teams, or service accounts are assigned to the role. The request requires the role's unique identifier in the URL path and accepts a payload containing the new assignments, typically including user IDs, team IDs, or service account IDs that should have this role. This is a privileged operation that requires appropriate permissions to manage role-based access control and is commonly used when restructuring team permissions or implementing access control changes across the Grafana instance.
      operationId: setRoleAssignments
      parameters:
      - name: roleUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetRoleAssignmentsCommand'
        required: true
      responses:
        '200':
          description: (empty)
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleAssignmentsDTO'
        '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'
        '404':
          description: NotFoundError is returned when the requested resource was not found.
          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/teams/{teamId}/roles:
    parameters: []
    post:
      tags:
      - Role
      summary: Grafana Add Team Role
      description: This API operation adds a role to a specific team in Grafana's access control system. It uses a POST request to the endpoint /access-control/teams/{teamId}/roles, where {teamId} is the unique identifier of the team receiving the new role assignment. The operation allows administrators to grant specific permissions and access levels to an entire team by associating a role with that team, streamlining permission management across multiple users who belong to the same team.
      operationId: addTeamRole
      parameters:
      - name: teamId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTeamRoleCommand'
        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'
        '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'
        '404':
          description: NotFoundError is returned when the requested resource was not found.
          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/teams/{teamId}/roles/{roleUID}:
    parameters: []
    delete:
      tags:
      - Role
      summary: Grafana Remove Team Role
      description: This API operation removes a specific role assignment from a team in Grafana's access control system. It uses a DELETE request to the endpoint /access-control/teams/{teamId}/roles/{roleUID}, where teamId identifies the target team and roleUID specifies the role to be removed. When executed, it revokes the specified role's permissions from the team, effectively removing that role's access rights from all members of that team without affecting other role assignments the team may have.
      operationId: removeTeamRole
      parameters:
      - name: roleUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: teamId
        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'
        '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'
        '404':
          description: NotFoundError is returned when the requested resource was not found.
          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/{userId}/roles:
    parameters: []
    post:
      tags:
      - Role
      summary: Grafana Add User Role
      description: This API operation adds a role to a specific user in Grafana's access control system by sending a POST request to the endpoint /access-control/users/{userId}/roles, where {userId} is replaced with the target user's identifier. The operation allows administrators to grant additional permissions and access rights to users by assigning them predefined or custom roles within the Grafana instance. This is typically used for managing user permissions and implementing role-based access control (RBAC) to ensure users have appropriate levels of access to dashboards, data sources, and other Grafana resources.
      operationId: addUserRole
      parameters:
      - name: userId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          contentEncoding: int64
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddUserRoleCommand'
        required: true
      responses:
        '200':
          description: An OKResponse is returned if the request was successful.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponseBody'
        '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'
        '404':
          description: NotFoundError is returned when the requested resource was not found.
          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/{userId}/roles/{roleUID}:
    parameters: []
    delete:
      tags:
      - Role
      summary: Grafana Remove User Role
      description: Removes a specific role assignment from a user in Grafana's access control system. This API endpoint deletes the association between a user (identified by userId) and a particular role (identified by roleUID), effectively revoking the permissions granted by that role from the user. The operation requires appropriate administrative privileges and is typically used when managing user permissions, reorganizing team structures, or removing access rights that are no longer needed. Upon successful execution, the user will no longer have the capabilities and access rights defined by the removed role, though they may still retain other role assignments.
      operationId: removeUserRole
      parameters:
      - name: global
        in: query
        description: A flag indicating if the assignment is global or not. If set to false, the default org ID of the authenticated user will be used from the request to remove assignment.
        style: form
        explode: true
        schema:
          type: boolean
      - name: roleUID
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: userId
        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'
        '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'
        '404':
          description: NotFoundError is returned when the requested resource was not found.
          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/{resource}/{resourceID}/builtInRoles/{builtInRole}:
    parameters: []
    post:
      tags:
      - Role
      summary: Grafana Set Resource Permissions For Built In Role
      description: This API operation allows administrators to configure and assign specific resource-level permissions to a built-in role within Grafana's access control system. By making a POST request to this endpoint with a specified resource type, resource ID, and built-in role identifier, you can define granular permissions that determine what actions the built-in role can perform on that particular resource. This is useful for customizing access control policies beyond default settings, enabling fine-grained security management where built-in roles like Viewer, Editor, or Admin can have their permissions tailored for specific dashboards, folders, data sources, or other Grafana resources without modifying the role globally.
      operationId: setResourcePermissionsForBuiltInRole
      parameters:
      - name: resource
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: resourceID
        in: path
        description: ''
        required: true
        schema:
          type: string
      - name: builtInRole
        in: path
        description: ''
        required: true
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setPermissionCommand'
        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'
        '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'
        '404':
          description: NotFoundError is returned when the requested resource was not found.
          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
components:
  schemas:
    RoleDTO:
      title: RoleDTO
      required:
      - created
      - description
      - displayName
      - group
      - name
      - uid
      - updated
      - version
      type: object
      properties:
        created:
          type: string
          contentEncoding: date-time
        delegatable:
          type: boolean
        description:
          type: string
        displayName:
          type: string
        global:
          type: boolean
        group:
          type: string
        hidden:
          type: boolean
        mapped:
          type: boolean
        name:
          type: string
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
          description: ''
        uid:
          type: string
        updated:
          type: string
          contentEncoding: date-time
        version:
          type: integer
          contentEncoding: int64
    SetRoleAssignmentsCommand:
      title: SetRoleAssignmentsCommand
      type: object
      properties:
        service_accounts:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
        teams:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
        users:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
    Permission:
      title: Permission
      type: object
      properties:
        action:
          type: string
        created:
          type: string
          contentEncoding: date-time
        scope:
          type: string
        updated:
          type: string
          contentEncoding: date-time
      description: Permission is the model for access control permissions
    RoleAssignmentsDTO:
      title: RoleAssignmentsDTO
      type: object
      properties:
        role_uid:
          type: string
        service_accounts:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
        teams:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
        users:
          type: array
          items:
            type: integer
            contentEncoding: int64
          description: ''
    setPermissionCommand:
      title: setPermissionCommand
      type: object
      properties:
        permission:
          type: string
    AddUserRoleCommand:
      title: AddUserRoleCommand
      type: object
      properties:
        global:
          type: boolean
        roleUid:
          type: string
    SuccessResponseBody:
      title: SuccessResponseBody
      type: object
      properties:
        message:
          type: string
    AddTeamRoleCommand:
      title: AddTeamRoleCommand
      type: object
      properties:
        roleUid:
          type: string
    ErrorResponseBody:
      title: ErrorResponseBody
      required:
      - message
      type: object
      properties:
        error:
          type: string
          description: Error An optional detailed description of the actual error. Only included if running in developer mode.
        message:
          type: string
          description: a human readable version of the error
        status:
          type: string
          description: 'Status An optional status to denote the cause of the error.


            For example, a 412 Precondition Failed error may include additional information of why that error happened.'
    UpdateRoleCommand:
      title: UpdateRoleCommand
      required:
      - description
      - displayName
      - group
      type: object
      properties:
        description:
          type: string
        displayName:
          type: string
        global:
          t

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grafana/refs/heads/main/openapi/grafana-role-api-openapi.yml