Athenian user API

openapi: 3.0.3
info:
  contact:
    email: admin@athenian.co
    name: the administrator by email
  description: 'Server version: {{ server_version }} built on {{ build_date }} @ [{{ commit }}](https://github.com/athenianco/athenian-api/commit/{{ commit }})


    Origin GitHub repository: [athenianco/api-spec](https://github.com/athenianco/api-spec).


    Authorization persists between sessions. Marks:

    * 🛡️ endpoint requires account admin privileges.

    * 👤 endpoint only works with JWT authentication.

    <details>

    <summary>List of common server errors.</summary>

    * __500__ endpoint crashed. We reported the incident to Sentry and will fix it soon! Please include the value of `instance` in the response if you contact the support. Repeating the request will not help, most probably.

    * __501__ some functions are missing, either because they are not implemented yet or a non-critical runtime dependency is not satisfied. Repeating the request will not help, guaranteed.

    * __502__ server crashed badly, either due to a memory access violation in native code or running out of memory. We reported this incident to Sentry and will fix it soon! Try repeating the request.

    * __503__ server has not fully launched yet, e.g. hasn''t connected to the database; server is shutting down; we are experiencing a partial outage. Try repeating the request.

    * __504__ endpoint took too much time and was interrupted. We reported the incident to Sentry and will see how to improve the performance. Repeating the request will not help, most probably.

    </details>'
  license:
    name: CC-BY-4.0
  title: '{{ title }} align 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 (deleted). This endpoint is allowed only for account admins.'
      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 organizations.
      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:
    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
    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
    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
    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
    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
    Datasource:
      description: A datasource configured for the account.
      enum:
      - github
      - jira
    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
    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
    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
    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
  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