swagger: '2.0'
info:
  version: 20.14.1
  title: Symphony Login 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.

    Authentication requests will expect the user to pass a token containing
    user identification information and signed by the user's private key

    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:
  /pubkey/authenticate:
    post:
      summary: Symphony Authenticate With Public Key
      description: >
        Based on an authentication request token signed by the caller's RSA
        private key,

        authenticate the API caller and return a session token.


        A HTTP 401 Unauthorized error is returned on errors during
        authentication (e.g. invalid user,

        malformed authentication token, user's public key not imported in the
        pod, invalid token signature etc.).
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: authenticateRequest
          in: body
          required: true
          schema:
            $ref: '#/definitions/AuthenticateRequest'
      tags:
        - Pubkey
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/Token'
        '401':
          description: Client is unauthorized to access this resource
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden to access this endpoint .
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Server error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
  /v1/pubkey/app/authenticate/extensionApp:
    post:
      summary: Symphony Authenticate Extension App With Public Key
      description: >
        Based on an authentication request token signed by the caller's RSA
        private key,

        authenticate the API caller and return a session token.


        A HTTP 401 Unauthorized error is returned on errors during
        authentication (e.g. invalid user,

        malformed authentication token, user's public key not imported in the
        pod, invalid token signature etc.).
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: authenticateRequest
          in: body
          required: true
          schema:
            $ref: '#/definitions/AuthenticateExtensionAppRequest'
      tags:
        - Pubkey
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/ExtensionAppTokens'
        '400':
          description: Request object is invalid
          schema:
            $ref: '#/definitions/Error'
        '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'
  /pubkey/app/authenticate:
    post:
      summary: Symphony Authenticate an App With Public Key
      description: >
        Based on an authentication request token signed by the application's RSA
        private key,

        authenticate the API caller and return a session token.


        A HTTP 401 Unauthorized error is returned on errors during
        authentication (e.g. invalid app,

        malformed authentication token, app's public key not imported in the
        pod, invalid token signature etc.).
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: authenticateRequest
          in: body
          required: true
          schema:
            $ref: '#/definitions/AuthenticateRequest'
      tags:
        - Pubkey
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/Token'
        '401':
          description: Client is unauthorized to access this resource
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden to access this endpoint .
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Server error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
  /pubkey/app/username/{username}/authenticate:
    post:
      summary: >-
        Symphony Authenticate an application in a delegated context to act on behalf of a user
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: sessionToken
          description: App Session authentication token.
          in: header
          required: true
          type: string
        - name: username
          description: the username
          in: path
          required: true
          type: string
      tags:
        - Pubkey
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/Token'
        '401':
          description: Client is unauthorized to access this resource
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden to access this endpoint .
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Server error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
  /pubkey/app/user/{userId}/authenticate:
    post:
      summary: >-
        Symphony Authenticate an application in a delegated context to act on behalf of a user
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: sessionToken
          description: App Session authentication token.
          in: header
          required: true
          type: string
        - name: userId
          description: the user ID
          in: path
          required: true
          type: integer
          format: int64
      tags:
        - Pubkey
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/Token'
        '401':
          description: Client is unauthorized to access this resource
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden to access this endpoint .
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Server error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
  /idm/tokens:
    post:
      summary: >-
        Symphony Returns a valid OAuth2 access token from a given session token to be used for authentication
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: sessionToken
          description: User session authentication token
          in: header
          required: true
          type: string
        - name: scope
          description: >
            Optional field used to get access with specific entitlements, use
            space separated list to define more that one
          in: query
          required: false
          type: string
      tags:
        - Idm
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/JwtToken'
        '401':
          description: Client is unauthorized to access this resource
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden to access this endpoint .
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Server error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
  /idm/keys:
    get:
      summary: Symphony Returns the Common Access Token (JWT) Public Keys as a JWKS
      x-since: 20.14
      description: >-
        This is a public endpoint, no authentication is required. The JWKS can
        be used to verify JWT issued by the idm/tokens endpoint. Since SBE
        20.14.
      produces:
        - application/json
      tags:
        - Idm
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/Jwks'
        '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.
  AuthenticateRequest:
    type: object
    description: Request body for pubkey authentication
    properties:
      token:
        type: string
        description: >-
          a JWT containing the caller's username or application appGroupId and
          an expiration date, signed by the caller's private key.
  AuthenticateExtensionAppRequest:
    type: object
    description: Request body for extension app authentication
    properties:
      appToken:
        type: string
        description: application generated token
      authToken:
        type: string
        description: >-
          a JWT containing the caller's username and an expiration date, signed
          by the caller's private key.
  ExtensionAppTokens:
    type: object
    properties:
      appId:
        description: Application ID
        type: string
      appToken:
        description: >
          This token generated by the application when calling authentication
          endpoint
        type: string
      symphonyToken:
        type: string
        description: >
          This token generated by Symphony and should be used by the application
          to verify that it's talking to Symphony.
      expireAt:
        type: integer
        format: int64
        description: unix timestamp when the token expired
  JwtToken:
    type: object
    properties:
      token_type:
        type: string
        description: Type of token, string "Bearer"
      expires_in:
        type: integer
        format: int64
        description: Duration of time the access token is granted for in seconds
      access_token:
        type: string
        description: >
          A JWT containing the caller's username or application, an expiration
          date and a set of entitlements related to the

          specified scope, signed by the caller's private key.
  Jwks:
    type: object
    properties:
      keys:
        type: array
        items:
          $ref: '#/definitions/JwksEntry'
  JwksEntry:
    type: object
    description: >-
      A JWK object as defined in
      https://datatracker.ietf.org/doc/html/rfc7517#section-4.
    additionalProperties:
      type: string
tags:
  - name: Idm
  - name: Pubkey