swagger: '2.0'
info:
  version: '20.14.1'
  title: Authenticator API
  description: |
    For bots and other on-premise processes to authenticate. Once
    authenticated, the bot will be able to use the methods described in
    serviceAPI.yaml and agentAPI.yaml.

    Connections to the servers will be over
    client authenticated TLS, the servers for this API will perform the
    authentication by inspecting the certificate presented by the
    SSLSocketClient.

    There will be two implementations of this API, one on your Pod
    and one on the Key Manager. In order to fully authenticate,
    an API client will have to call both of these implementations
    and pass both of the session tokens returned as headers in all
    subsequent requests to the Symphony API.
paths:
  '/v1/authenticate':
    post:
      summary: Authenticate.
      description: |
        Based on the SSL client certificate presented by the TLS layer, authenticate
        the API caller and return a session token.
      produces:
        - application/json
      tags:
        - CertificateAuthentication
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/Token'
        '400':
          description: 'Client error.'
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: 'Forbidden: Certificate authentication is not allowed for the requested user.'
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: 'Server error, see response body for further details.'
          schema:
            $ref: '#/definitions/Error'
  '/v1/app/pod/certificate':
    get:
      summary: |
        Retrieve the certificate that can be use to validate the JWT token obtain
        through the extension application authentication flow.
      produces:
        - application/json
      tags:
        - CertificatePod
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PodCertificate'
        '401':
          description: 'Client is unauthorized to access this resource'
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: 'Server error, see response body for further details.'
          schema:
            $ref: '#/definitions/Error'
  '/v1/logout':
    post:
      summary: Logout.
      description: |
        Logout a users session.
      parameters:
        - name: sessionToken
          description: the session token to logout.
          in: header
          required: true
          type: string
      produces:
        - application/json
      tags:
        - CertificateAuthentication
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/SuccessResponse'
        '400':
          description: 'Client error.'
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: 'Forbidden: Certificate authentication is not allowed for the requested user.'
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: 'Server error, see response body for further details.'
          schema:
            $ref: '#/definitions/Error'

definitions:
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
  Token:
    type: object
    properties:
      name:
        description: |
          The name of the header in which the token should be presented on subsequent API calls.
        type: string
      token:
        type: string
        description: |
          Authentication token that should be passed as header in each API rest calls.
          This should be considered opaque data by the client. It is not intended to contain any data interpretable by the
          client. The format is secret and subject to change without notice.
      authorizationToken:
        type: string
        description: |
          (Beta) Short lived access token built from a user session. This field is still on Beta, please continue using 
          the returned "token" instead.
  PodCertificate:
    type: object
    properties:
      certificate:
        description: Certificate in PEM format
        type: string
  SuccessResponse:
    type: object
    properties:
      message:
        type: string