Grafana Service Accounts API

openapi: 3.2.0
info:
  description: 'The Grafana backend exposes an HTTP API, the same API is used by the frontend to do

    everything from saving dashboards, creating users and updating data sources.'
  title: Grafana HTTP API. Service Accounts API
  contact:
    name: Grafana Labs
    url: https://grafana.com
    email: hello@grafana.com
  version: 0.0.1
servers:
- url: /api
security:
- basic: []
- api_key: []
tags:
- description: If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to Role-based access control permissions for more information.
  name: service_accounts
paths:
  /serviceaccounts:
    post:
      description: 'Required permissions (See note in the introduction for an explanation):

        action: `serviceaccounts:write` scope: `serviceaccounts:*`


        Requires basic authentication and that the authenticated user is a Grafana Admin.'
      tags:
      - service_accounts
      summary: Create service account
      operationId: createServiceAccount
      responses:
        '201':
          $ref: '#/components/responses/createServiceAccountResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceAccountForm'
  /serviceaccounts/search:
    get:
      description: 'Required permissions (See note in the introduction for an explanation):

        action: `serviceaccounts:read` scope: `serviceaccounts:*`'
      tags:
      - service_accounts
      summary: Search service accounts with paging
      operationId: searchOrgServiceAccountsWithPaging
      parameters:
      - name: Disabled
        in: query
        schema:
          type: boolean
      - name: expiredTokens
        in: query
        schema:
          type: boolean
      - description: 'It will return results where the query value is contained in one of the name.

          Query values with spaces need to be URL encoded.'
        name: query
        in: query
        schema:
          type: string
      - description: The default value is 1000.
        name: perpage
        in: query
        schema:
          type: integer
          format: int64
      - description: The default value is 1.
        name: page
        in: query
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/searchOrgServiceAccountsWithPagingResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '500':
          $ref: '#/components/responses/internalServerError'
  /serviceaccounts/{serviceAccountId}:
    get:
      description: 'Required permissions (See note in the introduction for an explanation):

        action: `serviceaccounts:read` scope: `serviceaccounts:id:1` (single service account)'
      tags:
      - service_accounts
      summary: Get single serviceaccount by Id
      operationId: retrieveServiceAccount
      parameters:
      - name: serviceAccountId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/retrieveServiceAccountResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
    delete:
      description: 'Required permissions (See note in the introduction for an explanation):

        action: `serviceaccounts:delete` scope: `serviceaccounts:id:1` (single service account)'
      tags:
      - service_accounts
      summary: Delete service account
      operationId: deleteServiceAccount
      parameters:
      - name: serviceAccountId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
    patch:
      description: 'Required permissions (See note in the introduction for an explanation):

        action: `serviceaccounts:write` scope: `serviceaccounts:id:1` (single service account)'
      tags:
      - service_accounts
      summary: Update service account
      operationId: updateServiceAccount
      parameters:
      - name: serviceAccountId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/updateServiceAccountResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceAccountForm'
  /serviceaccounts/{serviceAccountId}/tokens:
    get:
      description: 'Required permissions (See note in the introduction for an explanation):

        action: `serviceaccounts:read` scope: `global:serviceaccounts:id:1` (single service account)


        Requires basic authentication and that the authenticated user is a Grafana Admin.'
      tags:
      - service_accounts
      summary: Get service account tokens
      operationId: listTokens
      parameters:
      - name: serviceAccountId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/listTokensResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      description: 'Required permissions (See note in the introduction for an explanation):

        action: `serviceaccounts:write` scope: `serviceaccounts:id:1` (single service account)'
      tags:
      - service_accounts
      summary: CreateNewToken adds a token to a service account
      operationId: createToken
      parameters:
      - name: serviceAccountId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/createTokenResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddServiceAccountTokenCommand'
  /serviceaccounts/{serviceAccountId}/tokens/{tokenId}:
    delete:
      description: 'Required permissions (See note in the introduction for an explanation):

        action: `serviceaccounts:write` scope: `serviceaccounts:id:1` (single service account)


        Requires basic authentication and that the authenticated user is a Grafana Admin.'
      tags:
      - service_accounts
      summary: DeleteToken deletes service account tokens
      operationId: deleteToken
      parameters:
      - name: tokenId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: serviceAccountId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
components:
  responses:
    unauthorisedError:
      description: UnauthorizedError is returned when the request is not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    createTokenResponse:
      description: (empty)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewApiKeyResult'
    searchOrgServiceAccountsWithPagingResponse:
      description: (empty)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchOrgServiceAccountsResult'
    listTokensResponse:
      description: (empty)
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TokenDTO'
    internalServerError:
      description: InternalServerError is a general error indicating something went wrong internally.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    conflictError:
      description: ConflictError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    badRequestError:
      description: BadRequestError is returned when the request is invalid and it cannot be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    okResponse:
      description: An OKResponse is returned if the request was successful.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessResponseBody'
    forbiddenError:
      description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    createServiceAccountResponse:
      description: (empty)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceAccountDTO'
    retrieveServiceAccountResponse:
      description: (empty)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceAccountDTO'
    updateServiceAccountResponse:
      description: (empty)
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: integer
                format: int64
              message:
                type: string
              name:
                type: string
              serviceaccount:
                $ref: '#/components/schemas/ServiceAccountProfileDTO'
    notFoundError:
      description: NotFoundError is returned when the requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
  schemas:
    UpdateServiceAccountForm:
      type: object
      properties:
        isDisabled:
          type: boolean
        name:
          type: string
        role:
          type: string
          enum:
          - None
          - Viewer
          - Editor
          - Admin
        serviceAccountId:
          type: integer
          format: int64
    ErrorResponseBody:
      type: object
      required:
      - message
      properties:
        error:
          description: Error An optional detailed description of the actual error. Only included if running in developer mode.
          type: string
        message:
          description: a human readable version of the error
          type: string
        status:
          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.'
          type: string
    TokenDTO:
      type: object
      properties:
        created:
          type: string
          format: date-time
          example: '2022-03-23T10:31:02Z'
        expiration:
          type: string
          format: date-time
          example: '2022-03-23T10:31:02Z'
        hasExpired:
          type: boolean
          example: false
        id:
          type: integer
          format: int64
          example: 1
        isRevoked:
          type: boolean
          example: false
        lastUsedAt:
          type: string
          format: date-time
          example: '2022-03-23T10:31:02Z'
        name:
          type: string
          example: grafana
        secondsUntilExpiration:
          type: number
          format: double
          example: 0
    NewApiKeyResult:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        key:
          type: string
          example: glsa_REDACTED-GRAFANA-SERVICE-ACCOUNT-TOKEN
        name:
          type: string
          example: grafana
    ServiceAccountProfileDTO:
      type: object
      properties:
        accessControl:
          type: object
          additionalProperties:
            type: boolean
        avatarUrl:
          type: string
          example: /avatar/8ea890a677d6a223c591a1beea6ea9d2
        createdAt:
          type: string
          format: date-time
          example: '2022-03-21T14:35:33Z'
        id:
          type: integer
          format: int64
          example: 2
        isDisabled:
          type: boolean
          example: false
        isExternal:
          type: boolean
          example: false
        login:
          type: string
          example: sa-grafana
        name:
          type: string
          example: test
        orgId:
          type: integer
          format: int64
          example: 1
        requiredBy:
          type: string
          example: grafana-app
        role:
          type: string
          example: Editor
        teams:
          type: array
          items:
            type: string
          example: []
        tokens:
          type: integer
          format: int64
        uid:
          type: string
          example: fe1xejlha91xce
        updatedAt:
          type: string
          format: date-time
          example: '2022-03-21T14:35:33Z'
    CreateServiceAccountForm:
      type: object
      properties:
        isDisabled:
          type: boolean
          example: false
        name:
          type: string
          example: grafana
        role:
          type: string
          enum:
          - None
          - Viewer
          - Editor
          - Admin
          example: Admin
    AddServiceAccountTokenCommand:
      type: object
      properties:
        name:
          type: string
        secondsToLive:
          type: integer
          format: int64
    SearchOrgServiceAccountsResult:
      type: object
      properties:
        page:
          type: integer
          format: int64
        perPage:
          type: integer
          format: int64
        serviceAccounts:
          type: array
          items:
            $ref: '#/components/schemas/ServiceAccountDTO'
        totalCount:
          description: 'It can be used for pagination of the user list

            E.g. if totalCount is equal to 100 users and

            the perpage parameter is set to 10 then there are 10 pages of users.'
          type: integer
          format: int64
    ServiceAccountDTO:
      type: object
      properties:
        accessControl:
          type: object
          additionalProperties:
            type: boolean
          example:
            serviceaccounts:delete: true
            serviceaccounts:read: true
            serviceaccounts:write: true
        avatarUrl:
          type: string
          example: /avatar/85ec38023d90823d3e5b43ef35646af9
        id:
          type: integer
          format: int64
        isDisabled:
          type: boolean
          example: false
        isExternal:
          type: boolean
          example: false
        login:
          type: string
          example: sa-grafana
        name:
          type: string
          example: grafana
        orgId:
          type: integer
          format: int64
          example: 1
        role:
          type: string
          example: Viewer
        tokens:
          type: integer
          format: int64
          example: 0
        uid:
          type: string
          example: fe1xejlha91xce
    SuccessResponseBody:
      type: object
      properties:
        message:
          type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    basic:
      type: http
      scheme: basic