University of Calgary AuroraX Authenticate API

openapi: 3.2.0
info:
  title: AuroraX Authenticate API
  description: '## Overview


    This webpage is an interactive documentation interface for the AuroraX RESTful API.'
  version: stable
servers:
- url: https://api.aurorax.space
  description: AuroraX production server
  variables: {}
- url: https://api.staging.aurorax.space
  description: AuroraX staging server
  variables: {}
- url: http://localhost:8080/
  description: Local Development and Debugging
  variables: {}
tags:
- name: Authenticate
  description: Authenticate via email and password to get an Access Token. Use your API Key if you are building software without user interaction to run against the API.
paths:
  /api/v1/authenticate:
    post:
      tags:
      - Authenticate
      summary: Authenticate using email address and password
      description: 'Successfull authentication will return the HTTP header ''Authorization: Bearer . This header must be sent on all secure requests until /end_session is called or the access token times out (typically about 1/2 hr of inactivity).'
      operationId: authenticate
      requestBody:
        description: The authentication request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationRequest'
        required: true
      responses:
        '200':
          description: User authenticated. Send the 'Authorization' header found in the repsonse on all secure requests.
          headers:
            Authorization:
              description: Contains the access token required on all secure requrests.
              style: simple
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAccount'
        '400':
          description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this operation."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
        '401':
          description: 'Not Authorized

            The email address and password combination is incorrect.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
  /api/v1/authenticate/end_session:
    post:
      tags:
      - Authenticate
      summary: End user session
      description: End an authenticated user session (invalidate an Access Token). This is the equivelant of a logout action.
      operationId: endSession
      responses:
        '200':
          description: User session is ended and the Access Token is no longer valid.
        '400':
          description: "Missing parameters. \n\nPlease refer to the documentation for correctness of this operation."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDocument'
      security:
      - AccessToken: []
components:
  schemas:
    ErrorDocument:
      type: object
      properties:
        error_message:
          type: string
          description: If an error code exists, this will have contextual information for debugging
        error_code:
          type: string
          description: The error code
          enum:
          - Nil
          - Ok
          - NotPermitted
          - NotAuthorized
          - Duplicate
          - AssertionError
          - NotFound
          - ApplicationError
          - NotImplemented
          - ToManyRequests
          - Other
          - Conflict
          - NotAuthenticated
          - Unavailable
      description: This model provides additional details about error conditions that can be used for debugging.
    UserAccount:
      type: object
      properties:
        account_id:
          type: string
        upload_username:
          type: string
        email_address:
          type: string
        email_confirmed:
          type: string
          format: date-time
        first_name:
          type: string
        last_name:
          type: string
        role:
          type: string
          enum:
          - Administrator
          - Owner
          - Maintainer
          - User
        agree_terms:
          type: string
          format: date-time
        this_login:
          type: string
          format: date-time
        last_login:
          type: string
          format: date-time
        disabled:
          type: boolean
    AuthenticationRequest:
      required:
      - email_address
      - password
      type: object
      properties:
        email_address:
          type: string
          description: The email address of the user. An email will be sent to this address requesting confirmation of ownership.
        password:
          type: string
          description: This users password
      description: A container for authenticating a user by email address and password
  securitySchemes:
    AccessToken:
      type: http
      description: Send the Authorization header found in the response of a successful /authentication request on all  secure endpoints. Copy it verbatim to the request header. It is fine to send this header on all requests  to the API. The value in Swagger UI should only include the access token part (leave out 'Bearer').
      name: Authorization
      in: header
      scheme: bearer
      bearerFormat: Generated by server
    ApiKeyAuth:
      type: apiKey
      description: API keys are intended to be used by non-interactive software interfacing with the REST API. These can  be used instead of an Access Token approach.
      name: x-aurorax-api-key
      in: header