MConnectSDK/docs/client-auth-api.yaml

swagger: '2.0'
info:
  version: 1.0.0
  title: SCM Oauth Server
host: 'localhost:3000'
basePath: /client-auth
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /token:
    post:
      tags:
        - Device Flow
        - Private
      description: Obtain the device code (step 1)
      parameters:
        - name: device
          in: body
          description: Machine to authorize
          required: true
          schema:
            $ref: '#/definitions/Device'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/TokenResponse'
        '400':
          description: Malformed Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Client Id not Valid
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  /authorization:
    post:
      tags:
        - Device Flow
        - Public
      description: Authorize user (step 2) - called by MaestroConnect
      parameters:
        - name: user
          in: body
          description: User to authorize
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        '200':
          description: Success
        '400':
          description: Malformed Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  /verification:
    post:
      tags:
        - Device Flow
        - Private
      description: Token verification (step 3) - polling from the Machine
      parameters:
        - name: verification
          in: body
          description: Verification parameters
          required: true
          schema:
            $ref: '#/definitions/Verification'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/VerificationSuccessResponse'
        '400':
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  /refresh:
    post:
      tags:
        - Device Flow
        - Private
      description: Refresh Access Token
      parameters:
        - name: refreshToken
          in: body
          description: Refresh Token
          required: true
          schema:
            $ref: '#/definitions/RefreshToken'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/VerificationSuccessResponse'
        '400':
          description: Invalid Request (rfc 6749  5.2)
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Invalid Request (rfc 6749  5.2)
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Invalid Grant (rfc 6749  5.2)
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  /check:
    post:
      tags:
        - Private
      description: Check Access Token validity
      parameters:
        - name: accessToken
          in: body
          description: Access Token
          required: true
          schema:
            $ref: '#/definitions/AccessToken'
      responses:
        '200':
          description: Success
        '400':
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  /user_confirmation:
    get:
      tags:
        - Public
      description: Confirm user activation (link sent to user email address)
      parameters:
        - in: query
          name: user_code
          type: string
          description: User Code
          required: true
      responses:
        '200':
          description: Success
  /swagger:
    x-swagger-pipe: swagger_raw
definitions:
  Device:
    type: object
    required:
      - client_id
    properties:
      client_id:
        type: string
        description: Machine Identifier
  User:
    type: object
    required:
      - user_id
      - user_code
    properties:
      user_id:
        type: string
        description: MaestroConnect Identifier for the user
      user_code:
        type: string
        description: User code obtained in /token endpoint (step 1)
  Verification:
    type: object
    required:
      - client_id
      - device_code
    properties:
      client_id:
        type: string
        description: Machine Identifier
      device_code:
        type: string
        description: Device code obtained in /token endpoint (step 1)
  RefreshToken:
    type: object
    required:
      - refresh_token
    properties:
      refresh_token:
        type: string
  AccessToken:
    type: object
    required:
      - access_token
    properties:
      access_token:
        type: string
  TokenResponse:
    type: object
    required:
      - device_code
      - user_code
      - interval
      - expires_in
    properties:
      device_code:
        type: string
        description: Device code (needed in step 3)
      user_code:
        type: string
        description: User code (needed in step 2)
      verification_uri:
        type: string
        description: "called to complete authoriation workflow"
      interval:
        type: integer
      expires_in:
        type: integer
  VerificationSuccessResponse:
    type: object
    required:
      - access_token
      - refresh_token
      - token_type
      - expires
    properties:
      access_token:
        type: string
      refresh_token:
        type: string
      token_type:
        type: string
      expires:
        type: integer
      client:
        type: object
        properties:
          client_id: 
            type: string
          organizationCode:
            type: string
  RefreshTokenSuccessResponse:
    type: object
    required:
      - access_token
      - token_type
      - expires
    properties:
      access_token:
        type: string
      token_type:
        type: string
      expires:
        type: integer
  ErrorResponse:
    type: object
    required:
      - error
      - url
      - label
    properties:
      error :
        type: string
        example: human readable string explaining error cause
      url :
        type: string
        example: resource that returned error to log and repeat it
      label :
        type: string
        example: unique string that identifies a single error cause