Athenian Registration 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 }} Registration API'
  version: 2.1.86
servers:
- description: '{{ server_description }} - {{ server_url }}'
  url: '{{ server_url }}/v1'
tags:
- name: Registration
paths:
  /invite/accept:
    put:
      operationId: accept_invitation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptedInvitation'
        description: Accepted invitation details.
        required: true
        x-body-name: body
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitedUser'
          description: Details about the new user.
        400:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
          description: Something is wrong with the invitation URL.
        403:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Invitation is disabled or user is not a member of the GitHub organization.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Invitation was not found.
        409:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Concurrent requests.
        422:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSourceDataError'
          description: Account's installation has not finished yet.
      security:
      - bearerAuth: []
      summary: 👤 Accept the account membership invitation and finish registration.
      tags:
      - Registration
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.invitation_controller
  /invite/check:
    post:
      operationId: check_invitation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvitationLink'
        description: Checked invitation details.
        required: true
        x-body-name: body
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationCheckResult'
          description: 'Result of checking an invitation URL: invitation type, whether it is correctly formed and is enabled.'
      summary: Given an invitation URL, get its type (admin or regular account member) and…
      tags:
      - Registration
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.invitation_controller
  /invite/generate/{id}:
    get:
      operationId: gen_user_invitation
      parameters:
      - description: Numeric identifier of the account where to invite new users.
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: integer
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationLink'
          description: The invitation link has been generated successfully.
        403:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The user is forbidden to invite for this account.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The account was not found.
      security:
      - bearerAuth: []
      summary: 👤 Create an account invitation link for regular users.
      tags:
      - Registration
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.invitation_controller
  /invite/jira/{id}:
    get:
      operationId: gen_jira_link
      parameters:
      - description: Numeric identifier of the account who is installing JIRA integration.
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: integer
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationLink'
          description: The invitation link has been generated successfully.
        403:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The user is forbidden to invite for this account.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The account was not found.
      security:
      - bearerAuth: []
      summary: 👤 Generate a JIRA integration installation link.
      tags:
      - Registration
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.invitation_controller
  /invite/jira_progress/{id}:
    get:
      operationId: eval_jira_progress
      parameters:
      - description: Numeric identifier of the account that is installing JIRA.
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: integer
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallationProgress'
          description: Status of fetching JIRA data to Athenian.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The account does not exist or the user is not its member.
        422:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSourceDataError'
          description: The installation has not started yet.
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      summary: Return the current JIRA installation progress in Athenian
      tags:
      - Registration
      x-openapi-router-controller: athenian.api.controllers.invitation_controller
  /invite/progress/{id}:
    get:
      operationId: eval_metadata_progress
      parameters:
      - description: Numeric identifier of the account that is installing GitHub.
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: integer
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallationProgress'
          description: Status of fetching GitHub data to Athenian.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The account does not exist or the user is not its member.
        422:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSourceDataError'
          description: The installation has not started yet.
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      summary: Return the current GitHub installation progress in Athenian
      tags:
      - Registration
      x-openapi-router-controller: athenian.api.controllers.invitation_controller
components:
  schemas:
    InvitedUser:
      additionalProperties: false
      description: Details about the user who has accepted an invitation.
      example:
        user:
          id: github|60340681
          native_id: '60340681'
          login: gkwillie
          name: Groundskeeper Willie
          email: bot@athenian.co
          picture: https://avatars0.githubusercontent.com/u/60340681?v=4
          updated: 2020-01-23 12:00:00+00:00
        account: 0
      properties:
        account:
          description: Joined account ID.
          type: integer
        user:
          $ref: '#/components/schemas/User'
      required:
      - account
      - user
      type: object
    InvitationCheckResult:
      additionalProperties: false
      example:
        active: true
        type: regular
        valid: true
      properties:
        active:
          description: Value indicating whether the invitation is still enabled.
          type: boolean
        type:
          description: Invited user's account membership status.
          enum:
          - admin
          - regular
          type: string
        valid:
          description: Value indicating whether the invitation URL is correctly formed.
          type: boolean
      required:
      - valid
      type: object
    InvitationLink:
      additionalProperties: false
      example:
        url: https://app.athenian.co/i/deadf88d
      description: Product invitation URL.
      properties:
        url:
          description: Invitation URL. Users are supposed to click it and become admins or regular account members.
          format: url
          type: string
      required:
      - url
      type: object
    AcceptedInvitation:
      additionalProperties: false
      example:
        url: https://app.athenian.co/i/deadf88d
        email: vadim@athenian.co
      description: Request for entering the product.
      properties:
        email:
          description: Calling user's email address.
          format: email
          type: string
        name:
          description: Calling user's name.
          type: string
        url:
          description: Invitation URL. Users are supposed to click it and become admins or regular account members.
          format: url
          type: string
      required:
      - url
      type: object
    NoSourceDataError:
      $ref: '#/components/schemas/GenericError'
    TableFetchingProgress:
      additionalProperties: false
      description: Used in InstallationProgress.tables to indicate how much data has been loaded in each DB table.
      example:
        fetched: 50
        name: Commit
        total: 100
      properties:
        fetched:
          description: How many records have been stored in the DB table so far.
          minimum: 0
          type: integer
        name:
          description: DB table identifier.
          type: string
        total:
          description: How many records the DB table is expected to have.
          minimum: 1
          type: integer
      required:
      - fetched
      - name
      - total
      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
    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
    InstallationProgress:
      additionalProperties: false
      description: 'Status of fetching data to Athenian.

        GitHub progress always returns `owner` and `repositories`.

        '
      example:
        tables:
        - fetched: 50
          name: Commit
          total: 100
        - fetched: 0
          name: PullRequest
          total: 20
        finished_date: 2020-01-23 04:56:07+00:00
        started_date: 2020-01-23 06:56:07+00:00
        owner: vmarkovtsev
        repositories: 30
      properties:
        started_date:
          description: Date and time when the historical data collection began.
          format: date-time
          type: string
        finished_date:
          description: Date and time when the historical data collection ended.
          format: date-time
          type:
          - string
          - 'null'
        owner:
          description: Login of the person who installed the metadata.
          type: string
        repositories:
          description: Number of discovered repositories.
          minimum: 0
          type: integer
        tables:
          example:
          - fetched: 50
            name: Commit
            total: 100
          - fetched: 0
            total: 200
            name: PullRequest
          items:
            $ref: '#/components/schemas/TableFetchingProgress'
          type: array
      required:
      - finished_date
      - started_date
      - tables
      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
  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