Loadsmart Authentication API

openapi: 3.2.0
info:
  title: Opendock Nova API Documentation Authentication API
  description: '## Welcome to Opendock Nova! #### What is Opendock Nova? Opendock is an online dock appointment scheduling tool. Facilities such as warehouses, distribution centers, and

    manufacturing plants use it to organize their docks and schedule appointments for outbound pickups and inbound

    deliveries. You can read all our knowledge base

    articles here. We now provide an SSO option for User Authentication. Read

    the docs here. ---


    ## Our APIs


    We have 3 main APIs:


    - REST API called _Neutron_ for performing standard HTTP operations. - Real-time API called _Subspace_ for receiving streaming events whenever objects are Created/Updated/Deleted. - A **"Reference Number Validation"** aka "PO Validation" _protocol_ for validating PO numbers (or similar) before an

    appointment is scheduled. Detailed documentation for it can be found

    here: PO/Ref Number Validation Implementation


    ---


    ## Neutron - REST API


    All endpoints are listed below. Depending on your User Role, some may be forbidden. Almost all endpoints expect a simple

    JWT token to be set in the `Authorization: Bearer` HTTP header. Read more about Bearer

    tokens here. ### Base URL


    The base URL is the same as it is for this document (look at the current URL in your browser''s address bar). For

    example, our production Neutron Base URL is https://neutron.opendock.com. ### Authentication


    To start, call the `POST /auth/login` endpoint to exchange your user credentials (email + password) for a simple JWT

    token. If you don''t have an account yet, reach out to your account admin or contact us for further help. If login is successful, the response will be a JWT token to use as your `Bearer` header as described above. The JWT expiration time depends on your User Role as well as other factors. You may base64-decode your JWT token to view

    more technical details about it. #### Test it:


    To test that your auth headers are set correctly, call the `GET /auth/me` endpoint. It will return a JSON payload with

    your User information. ---


    ## Subspace - Real-time Streaming API


    Subspace is a _read-only_ API that allows your system to recieve streaming real-time information about changes to your

    Appointments, Warehouses, Docks, etc. Using Subspace you can implement a "push"-based approach to your integration instead of relying only on "poll"-ing

    methods (which can be inefficient). Subpsace is based on the famous `socket.io` library. ### Choosing a socket.io Client


    The socket.io project provides a JavaScript client library that works in the browser as well as NodeJS. However there

    are also client implementations in many other languages including C#, Java, Python, and Go, so you should select the

    appropriate client for your project. A good overview of socket.io and a list of client implementations can be found

    here: Socket.IO Introduction


    **NOTE:** Currently Opendock uses socket.io server **v4.x** so please make sure to select an appropriate socket.io

    client version that is protocol compatible. ### Connecting and Authentication


    The base connection URL is the same as the base URL for Neutron above, except with the word "subspace" instead of "

    neutron". For example, our production Subspace connection URL

    is wss://subspace.opendock.com. For convenience, the same JWT token obtained from the Neutron `/auth/login` endpoint above is used for Subspace

    authentication. Connecting and Authenticating are done in a single operation: simply connect to the following `wss` URL:


    ```

    ?token=

    ```


    That can be a little confusing to parse. Here''s a real-life example connection string:


    ```

    wss://subspace.opendock.com?token=eyJhbGciOiJIUzI1Ni...(full token continues)

    ```


    **NOTE:** Currently Opendock only supports the `websocket` transport, so you must specify this in your connection

    settings. Here''s an example of connecting to Subspace using the JavaScript client:


    ```JavaScript

    // NOTE: we assume "accessToken" was already obtained earlier via a call to ''/auth/login''.'
  version: v4.144.0 - 39b4253
  contact: {}
servers:
- url: https://neutron.opendock.com
  description: Production Server
- url: https://neutron.staging.opendock.com
  description: Staging Server
tags:
- name: Authentication
paths:
  /auth/login:
    post:
      operationId: AuthController_login
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginDto'
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponseDto'
      tags:
      - Authentication
      summary: Auth controller login
      x-summary-source: derived
  /auth/refresh:
    get:
      operationId: AuthController_refresh
      parameters: []
      responses:
        '200':
          description: Refreshed token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponseDto'
      tags:
      - Authentication
      security:
      - bearer: []
      summary: Auth controller refresh
      x-summary-source: derived
  /auth/profile:
    get:
      operationId: AuthController_getProfile
      parameters: []
      responses:
        '200':
          description: Current authenticated user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProfileResponseDto'
      tags:
      - Authentication
      security:
      - bearer: []
      summary: Auth controller get profile
      x-summary-source: derived
  /auth/me:
    get:
      operationId: getAuthMe
      parameters: []
      responses:
        '200':
          description: Current authenticated user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProfileResponseDto'
      tags:
      - Authentication
      security:
      - bearer: []
      summary: Auth controller get profile
      x-summary-source: derived
      x-operation-id-source: normalized
      x-operation-id-original: AuthController_getProfile
components:
  schemas:
    AuthProfileResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 867cef72-a49d-42f1-a605-f49c5fbc7ae4
        createDateTime:
          type: string
          format: date-time
          example: '2024-07-09T20:14:00.475Z'
        createdBy:
          type: string
          format: uuid
          example: 867cef72-a49d-42f1-a605-f49c5fbc7ae4
        lastChangedDateTime:
          type: string
          format: date-time
          example: '2026-02-27T14:33:00.461Z'
        lastChangedBy:
          type: string
          format: uuid
          example: 867cef72-a49d-42f1-a605-f49c5fbc7ae4
        isActive:
          type: boolean
          example: true
        tags:
          example: null
          type:
          - array
          - 'null'
          items:
            type: string
        email:
          type: string
          example: user@example.com
        firstName:
          type: string
          example: Cave
        lastName:
          type: string
          example: Johnson
        phone:
          type:
          - object
          - 'null'
          example: null
        extension:
          type:
          - object
          - 'null'
          example: null
        isEmailVerified:
          type: boolean
          example: true
        role:
          type: string
          enum:
          - role_owner
          - role_admin
          - role_operator
          - role_attendant
          - role_spectator
          - role_yard_driver
          - role_carrier_admin
          - role_carrier
          - role_base
          example: role_owner
        companyId:
          type:
          - object
          - 'null'
          format: uuid
          example: null
        orgId:
          type:
          - object
          - 'null'
          format: uuid
          example: 7e77fbe1-9517-44ce-b08b-5a18b478b79f
        warehouseAccessList:
          example: null
          type:
          - array
          - 'null'
          items:
            type: string
        invalidLoginAttempts:
          type:
          - object
          - 'null'
          example: null
        tcConfirmedAt:
          type:
          - object
          - 'null'
          format: date-time
          example: '2024-07-09T20:14:20.814Z'
        lastLoginAt:
          type:
          - object
          - 'null'
          format: date-time
          example: '2026-02-27T14:33:00.459Z'
        passwordResetRequired:
          type: boolean
          example: false
        passwordResetEmailSentAt:
          type:
          - object
          - 'null'
          format: date-time
          example: null
        orgIsActive:
          type: boolean
          example: true
        orgName:
          type: string
          example: My Organization
        orgCreateDateTime:
          type: string
          format: date-time
          example: '2024-07-09T20:14:43.349Z'
        orgType:
          type: string
          example: Client
      required:
      - id
      - createDateTime
      - createdBy
      - lastChangedDateTime
      - isActive
      - email
      - firstName
      - lastName
      - isEmailVerified
      - role
    LoginDto:
      type: object
      properties:
        email:
          type: string
          example: user@example.com
          description: User email address
        password:
          type: string
          example: P@ssw0rd!
          description: User password
      required:
      - email
      - password
    LoginResponseDto:
      type: object
      properties:
        access_token:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          description: JWT access token
        expires_in:
          type: number
          example: 3600
          description: Token expiration time in seconds
      required:
      - access_token
      - expires_in
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http