Athenian User API

openapi: 3.2.0
info:
  contact:
    email: admin@athenian.co
    name: the administrator by email
  description: 'Server version: {{ server_version }} built on {{ build_date }} @ {{ commit }}


    Origin GitHub repository: athenianco/api-spec.'
  license:
    name: CC-BY-4.0
  title: '{{ title }} User API'
  version: 2.1.86
servers:
- description: '{{ server_description }} - {{ server_url }}'
  url: '{{ server_url }}/v1'
tags:
- name: User
paths:
  /account/user:
    put:
      operationId: change_user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUserChangeRequest'
        x-body-name: body
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
          description: Effective account members.
        403:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Requesting user is not an admin of the account.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The account was not found.
      security:
      - bearerAuth: []
      summary: '🛡️👤 Change the status of an account member: regular, admin, or banished…'
      tags:
      - User
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.user_controller
  /account/{id}/details:
    get:
      operationId: get_account_details
      parameters:
      - description: Numeric identifier of the account. The user must belong to that account. To find out which accounts the user belongs to, see `/user`.
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: integer
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
          description: List of the account members and installed GitHub and JIRA organizations.
        403:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The user does not have access to this account.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The account was not found.
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      summary: List the calling user's account members and installed GitHub and JIRA…
      tags:
      - User
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.user_controller
  /account/{id}/features:
    get:
      operationId: get_account_features
      parameters:
      - description: Numeric identifier of the account. The user must belong to that account. To find out which accounts the user belongs to, see `/user`.
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: integer
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductFeatures'
          description: List of the enabled product features for the account.
        403:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The user does not have access to this account.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The account was not found.
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      summary: List the product features enabled for the account
      tags:
      - User
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.user_controller
  /share:
    post:
      operationId: save_share
      requestBody:
        content:
          application/json:
            schema:
              type: object
        x-body-name: body
      responses:
        200:
          content:
            application/json:
              schema:
                type: string
          description: Saved share identifier.
        400:
          $ref: '#/components/responses/InvalidRequestErrorResponse'
      security:
      - bearerAuth: []
      summary: 👤 Save the state of UI views and return a reference
      tags:
      - User
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.share_controller
  /share/{id}:
    get:
      operationId: get_share
      parameters:
      - description: Reference to the share previously saved by `PUT /share`.
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Share'
          description: Saved state of the UI views.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Share does not exist or the user is not allowed to access.
      security:
      - bearerAuth: []
      summary: 👤 Load the previously saved state of the UI views
      tags:
      - User
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.share_controller
  /user:
    get:
      operationId: get_user
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: 'Information about the calling user: name, email, login, etc.'
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      summary: Show details about the calling user
      tags:
      - User
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.user_controller
components:
  schemas:
    Datasource:
      description: A datasource configured for the account.
      enum:
      - github
      - jira
    ProductFeature:
      additionalProperties: false
      description: Client-side product feature definition.
      example:
        name: jira
        parameters:
          epics: true
          labels: false
      properties:
        name:
          type: string
        parameters:
          oneOf:
          - type: number
          - type: string
          - type: object
      required:
      - name
      - parameters
      type: object
    AccountUserChangeRequest:
      additionalProperties: false
      description: Request to change an account member's status.
      example:
        user: github|60340680
        account: 1
        status: regular
      properties:
        account:
          description: Account ID.
          type: integer
        user:
          description: Account member ID.
          type: string
        status:
          description: Account membership role.
          enum:
          - regular
          - admin
          - banished
          type: string
      required:
      - account
      - status
      - user
      type: object
    AccountStatus:
      additionalProperties: false
      description: Status of the user's account membership.
      example:
        is_admin: true
        expired: false
        stale: false
        has_jira: true
        has_ci: true
        has_deployments: true
      properties:
        is_admin:
          description: Indicates whether the user is an account administrator.
          type: boolean
        expired:
          description: Indicates whether the account is disabled.
          type: boolean
        stale:
          description: Indicates whether the account is temporarily not receiving data updates.
          type: boolean
        has_jira:
          description: Indicates whether the account installed the integration with JIRA.
          type: boolean
        has_ci:
          description: Indicates whether the account permitted the access to check suites.
          type: boolean
        has_deployments:
          description: Indicates whether the account has submitted at least one deployment.
          type: boolean
      required:
      - expired
      - has_ci
      - has_deployments
      - has_jira
      - is_admin
      - stale
      type: object
    JIRAInstallation:
      additionalProperties: false
      description: Information about a link with JIRA.
      example:
        url: https://athenianco.atlassian.net
        projects:
        - DEV
        - ENG
      properties:
        url:
          description: JIRA base URL.
          format: url
          type: string
        projects:
          description: List of accessible project keys.
          items:
            type: string
          type: array
      required:
      - projects
      - url
      type: object
    User:
      additionalProperties: false
      description: User details. "updated" and "accounts" are populated only for the calling user.
      example:
        id: github|60340680
        native_id: '60340680'
        login: gkwillie
        name: Groundskeeper Willie
        email: bot@athenian.co
        picture: https://avatars0.githubusercontent.com/u/60340680?v=4
        updated: 2020-01-23 12:00:00+00:00
        accounts:
          1:
            is_admin: true
            expired: false
            has_jira: true
            has_ci: true
            has_deployments: true
            stale: false
          2:
            is_admin: false
            expired: false
            has_jira: false
            has_ci: true
            has_deployments: false
            stale: false
      properties:
        accounts:
          additionalProperties:
            $ref: '#/components/schemas/AccountStatus'
          description: Mapping from user's account ID the membership status.
          type: object
        email:
          description: Email of the user.
          type: string
        id:
          description: Auth0 user identifier.
          type: string
        impersonated_by:
          description: Identifier of the super admin user who is acting on behalf of.
          type: string
        login:
          description: Auth backend user login name.
          type: string
        native_id:
          description: Auth backend user identifier.
          type: string
        name:
          description: Full name of the user.
          type: string
        picture:
          description: Avatar URL of the user.
          type: string
        updated:
          description: Date and time of the last profile update.
          format: date-time
          type: string
      required:
      - id
      - login
      - native_id
      type: object
    InvalidRequestError:
      allOf:
      - $ref: '#/components/schemas/GenericError'
      - properties:
          pointer:
            description: Path to the offending request item.
            example: .granularity
            type: string
        type: object
    ProductFeatures:
      description: Enabled client-side product features.
      example:
      - name: expires_at
        parameters: '2030-01-01T00:00:00Z'
      - name: jira
        parameters:
          epics: true
          labels: false
      items:
        $ref: '#/components/schemas/ProductFeature'
      type: array
    Organization:
      additionalProperties: false
      description: GitHub organization details.
      example:
        name: Athenian
        login: athenianco
        avatar_url: https://avatars3.githubusercontent.com/u/58329504?s=200&v=4
      properties:
        name:
          type: string
        avatar_url:
          type: string
        login:
          type: string
      required:
      - avatar_url
      - login
      - name
      type: object
    GenericError:
      example:
        detail: 'Unsupported metric: pr-xxx-time'
        status: 400
        title: Bad request syntax or unsupported method.
        type: /errors/InvalidRequestError
      properties:
        detail:
          description: Human-readable explanation specific to this occurrence of the problem.
          example: 'Unsupported metric: pr-xxx-time'
          type: string
        instance:
          description: URI reference that identifies the specific occurrence of the problem. It is `null` for 4xx, Sentry event ID for 5xx.
          example: 2763c4eabd7240f59829ee1a02546293
          type: string
        status:
          description: Duplicated HTTP status code.
          example: 400
          type: integer
        title:
          description: Short, human-readable summary of the problem type.
          example: Bad request syntax or unsupported method.
          type: string
        type:
          description: URI reference that identifies the problem type (RFC 7807).
          example: /errors/InvalidRequestError
          type: string
      required:
      - status
      - title
      - type
      type: object
    Account:
      additionalProperties: false
      description: Account members ("updated" and "accounts" are not populated) and installed GitHub organizations.
      example:
        regulars:
        - id: github|24828976
          native_id: '24828976'
          login: jjdoe
          name: Jane Josephine Doe
          email: janedoe@exampleco.com
          picture: https://exampleco.com/janedoe/me.jpg
          updated: 2020-01-23 12:00:00+00:00
        - id: github|24828977
          native_id: '24828977'
          login: jjdoe
          name: Jane Josephine Doe
          email: janedoe@exampleco.com
          picture: https://exampleco.com/janedoe/me.jpg
          updated: 2020-01-23 12:00:00+00:00
        admins:
        - id: github|24828978
          native_id: '24828978'
          login: jjdoe
          name: Jane Josephine Doe
          email: janedoe@exampleco.com
          picture: https://exampleco.com/janedoe/me.jpg
          updated: 2020-01-23 12:00:00+00:00
        - id: github|24828979
          native_id: '24828979'
          login: jjdoe
          name: Jane Josephine Doe
          email: janedoe@exampleco.com
          picture: https://exampleco.com/janedoe/me.jpg
          updated: 2020-01-23 12:00:00+00:00
        organizations:
        - name: Athenian
          login: athenianco
          avatar_url: https://avatars3.githubusercontent.com/u/58329504?s=200&v=4
        datasources:
        - github
        - jira
        jira:
          url: https://athenianco.atlassian.net
          projects:
          - DEV
          - ENG
      properties:
        admins:
          description: List of admin users.
          items:
            $ref: '#/components/schemas/User'
          type: array
        regulars:
          description: List of non-admin users.
          items:
            $ref: '#/components/schemas/User'
          type: array
        organizations:
          description: List of installed GitHub organizations.
          items:
            $ref: '#/components/schemas/Organization'
          type: array
        datasources:
          description: The list of datasources configured for the account.
          items:
            $ref: '#/components/schemas/Datasource'
          type: array
        jira:
          $ref: '#/components/schemas/JIRAInstallation'
      required:
      - admins
      - organizations
      - regulars
      - datasources
      type: object
    Share:
      additionalProperties: false
      description: Saved UI views state with metadata.
      example:
        author: Vadim Markovtsev
        created: 2022-05-05 12:00:00+00:00
        data:
          whatever: 777
      properties:
        author:
          description: User name who submitted.
          type: string
        created:
          description: Submission timestamp.
          format: date-time
          type: string
        data:
          description: Saved object.
          type: object
      required:
      - author
      - created
      - data
      type: object
  responses:
    InvalidRequestErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvalidRequestError'
      description: The request is invalid.
  securitySchemes:
    apiKeyAuth:
      description: 'Authorization by the value of `X-API-Key` header aka API token.

        The tokens are user- and account-specific. Create them by calling `/token/create`.

        The server automatically inserts `account` in the request''s body if it was not

        supplied by the user.'
      in: header
      name: X-API-Key
      type: apiKey
      x-apikeyInfoFunc: athenian.api.controllers.security_controller.info_from_apiKeyAuth
    bearerAuth:
      bearerFormat: JWT
      description: 'Regular JSON Web Token authorization powered by Auth0.

        The server expects an `Authorization: Bearer <token>` header and checks `<token>` by

        sending it to Auth0. Visit [{{ server_url | replace("api", "app") }}/bearer]({{ server_url | replace("api", "app") }}/bearer)

        to copy your current JWT that will expire within 24 hours.'
      scheme: bearer
      type: http
      x-bearerInfoFunc: athenian.api.controllers.security_controller.info_from_bearerAuth