openapi: 3.2.0
info:
  title: TMT API specs Authenticate API
  termsOfService: https://viteza.tmtid.com/download-terms-and-conditions
  contact:
    name: TMT Support
    email: support@tmtid.com
    url: https://www.tmtid.com
  x-logo:
    url: https://www.tmtid.com/developer/authenticate_logo_png.png
    altText: TMT Authenticate
  version: 1.1.2
  description: Authenticate user with MNO or OTP. These endpoints can be directly called by the users.
servers:
- url: https://auth-staging-api.tmtid.dev/v1
  description: Pre-Production
- url: https://auth-api.tmtanalysis.com/v1
  description: Production Server
schemes:
- https
tags:
- name: Authenticate
  description: Authenticate user with MNO or OTP. These endpoints can be directly called by the users.
paths:
  /oauth/token:
    post:
      tags:
      - Authenticate
      summary: This phase is where the Customer requests authorization to perform an authentication for a given device.
      description: 'This phase is where the Customer requests authorization to perform an authentication for a given device.


        The Customer requests permission to make an Authentication query and receives a timebound token for that transaction. The Customer also must request which authentication technology is required for this transaction.'
      operationId: getAccessToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AuthRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad request:
                  description: The value for the required field is missing or it is invalid
                  value:
                    error: invalid_request
                    error_description: The required field is missing or it is invalid.
                Invalid Grant:
                  description: Invalid grant type requested by customer
                  value:
                    error: invalid_grant
                    error_description: The requested grant type is invalid, unknown or malformed.
                Invalid Scope:
                  description: 'Multiple scopes were requested

                    Invalid scope requested by customer


                    '
                  value:
                    error: invalid_scope
                    error_description: The requested scope is invalid, unknown or malformed.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  description: 'User failed to authenticate with bisector for authenticate scope


                    User failed to authenticate for authenticate/otp service


                    User tried to authenticate with a key in an environment not corresponding to the service requested


                    '
                  value:
                    error: unauthorized_client
                    error_description: Authentication required
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Service Unavailable:
                  description: Bisector is down or not responding
                  value:
                    error: temporarily_unavailable
                    error_description: Service is unavailable
      security:
      - basic: []
  /get_config:
    post:
      tags:
      - Authenticate
      summary: The get_config endpoint will return specific instructions on how to begin the session with the relevant MNO and how to send the OTP message.
      description: 'The get_config endpoint will return specific instructions on how to begin the session with the relevant MNO and how to send the OTP message.


        The Customer requests the specific telephone number that requires authentication. In response to this stage TMT ID will return the specific uri that the handset must call for the Silent Authentication (where appropriate).'
      operationId: getConfig
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GetAuthUrl'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationUri'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad request:
                  description: The value for the required field is missing or it is invalid
                  value:
                    error: invalid_request
                    error_description: The required field is missing or it is invalid.
                Invalid Callback URL:
                  description: The callback_url from the query is not in the list of allowed callback_urls for the customer
                  value:
                    error: invalid_redirect_uri
                    error_description: The redirect_uri provided is invalid.
                Invalid Network:
                  description: "Invalid CCID returned.\n\n Invalid SPID returned.\n\nCurrent network not found.\n\n"
                  value:
                    error: invalid_request
                    error_description: Network provided is invalid
                Invalid Request:
                  description: "The phone number is invalid.\n\n The phone number requested is not supported.\n\n"
                  value:
                    error: invalid_request
                    error_description: The provided request is invalid
                Invalid Token:
                  description: " The scope is not present in the token.\nThe scope is not valid in the token.\n\nThe customer is not present in the token. \n\n The customer is not valid in the token.\n\n"
                  value:
                    error: invalid_request
                    error_description: The provided token is invalid.
                Redirect URI not supported:
                  description: The customer provided redirect_uri on get_config endpoint for a network that does not support callback on redirect_uri.
                  value:
                    error: invalid_request
                    error_description: Network does not support callback on redirect_uri
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  description: 'Country access is not allowed


                    '
                  value:
                    error: unauthorized_client
                    error_description: Authentication required
      security:
      - paseto_token: []
  /validate:
    post:
      tags:
      - Authenticate
      summary: The validate endpoint will return whether the phone number was validated successfully or not and the service used in order to achieve the authentication.
      description: 'The validate endpoint will return whether the phone number was validated successfully or not and the service used in order to achieve the authentication.


        Security mechanism that allows the Customer to check with TMT ID that a handset had correctly authenticated.'
      operationId: validateUserSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetResult'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Invalid request. Received both 'payload' and 'code' in validate request.:
                  value:
                    error: invalid_request
                    error_description: Invalid request. Received both 'payload' and 'code' in validate request.
                The required field `code` is missing or is invalid.:
                  value:
                    error: invalid_request
                    error_description: The required field `code` is missing or is invalid.
                The required field `payload` is missing or is invalid.:
                  value:
                    error: invalid_request
                    error_description: The required field `payload` is missing or is invalid.
                The value for the required field is missing or it is invalid:
                  value:
                    error: invalid_request
                    error_description: The required field is missing or it is invalid.
      security:
      - paseto_token: []
components:
  schemas:
    AuthorizeRequestConfig:
      oneOf:
      - type: object
        required:
        - authorization_uri
        - request_type
        - ajax
        properties:
          ajax:
            type: boolean
            description: Flag  that confirm the request can be completed via ajax or not.
            example: 'true'
          authorization_uri:
            type: string
            description: The uri that needs to be called in order to identify the phone number.
            example: http://example.com/session
          request_config:
            allOf:
            - $ref: '#/components/schemas/VendorAuthorizationConfig'
          request_type:
            type: string
            description: Provided in order to inform users how to configure the request with Mobile Network Operator.This can be GET or POST, the dafault is GET.
            example: POST
      - $ref: '#/components/schemas/ErrorResponse'
    VendorAuthorizationConfig:
      type: object
      properties:
        headers:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
        parameters:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
    AuthRequest:
      type: object
      required:
      - scope
      - grant_type
      properties:
        grant_type:
          type: string
          description: The value must be “client_credentials”.By passing this value the service will return an access_token for direct access to the services.
          example: client_credentials
        scope:
          type: string
          description: Scope must contain the requested services. It can be authenticate and/or otp concatenated with a “+”.
          example: authenticate+otp
    ErrorResponse:
      type: object
      required:
      - error
      - error_description
      properties:
        error:
          type: string
        error_description:
          type: string
    GetAuthUrl:
      type: object
      required:
      - msisdn
      - client_ip
      properties:
        client_ip:
          type: string
          description: The IP of the user needed to be authenticated. This is required by some MNO’s for validation.
          example: 11.22.33.44
        correlation_id:
          type:
          - string
          - 'null'
          description: It is used to correlate the transaction across all components(authenticate, validate). It must be unique to the instance of the transaction.
          example: Noo7siol1Yj763XTRDidILTv96ly9kFS
        msisdn:
          type: string
          description: The phone number that needs to be authenticated by our system in E.164 format.
          example: '+44770123456'
        redirect_uri:
          type:
          - string
          - 'null'
          description: Predefined callback url to be used in the session and send the request back to the client
    GetResult:
      type: object
      required:
      - id_token
      properties:
        code:
          type:
          - string
          - 'null'
          description: Code obtained from the authenticate request on redirect_uri
          example: 64a5b19-457a-4d30-a5c4-038c62dcssfg3
        correlation_id:
          type:
          - string
          - 'null'
          description: The correlation_id submitted through the get_config request
          example: Noo7siol1Yj763XTRDidILTv96ly9kFS
        id_token:
          type: string
          description: Provided in the get_config request
          example: v4.public.eyJ2ZW5kb3JfdHlwZSI6IkVFIiwianRp…
        otp_code:
          type:
          - string
          - 'null'
          description: Provided only if we need to validate the user using the OTP service
          example: '123456'
        payload:
          description: JSON Response obtained from the authenticate or otp request.
    AuthResponse:
      type: object
      required:
      - token_type
      - access_token
      - expires_in
      properties:
        access_token:
          type: string
          description: The access_token is a security token that contains Claims about the authenticated user and requested services.
          example: v4.public.eyJzY29wZSI6ImF1dGgrb3RwIiwidXNlcl9pZ…
        expires_in:
          type: integer
          format: int64
          description: The time-to-live of the Access Token in seconds since the response was generated. The default value is 3600 (seconds)
          example: '3600'
          minimum: 0
        token_type:
          type: string
          description: Always "Bearer"
          example: Bearer
    ValidateResponse:
      type: object
      required:
      - authenticated
      - service
      properties:
        authenticated:
          type: boolean
          description: This value will be true or false depending on if the user was successfully authenticated or not.
          example: 'true'
        correlation_id:
          type:
          - string
          - 'null'
          example: Noo7siol1Yj763XTRDidILTv96ly9kFS
        service:
          type: string
          description: Value authenticate or otp depending on the type of authentication mechanism used
          example: authenticate
    AuthorizationUri:
      type: object
      required:
      - id_token
      - expires_in
      properties:
        authorize:
          allOf:
          - $ref: '#/components/schemas/AuthorizeRequestConfig'
        correlation_id:
          type:
          - string
          - 'null'
          description: Provided only if the correlation_id parameter was  submitted through in the /get_config request.
          example: Noo7siol1Yj763XTRDidILTv96ly9kFS
        expires_in:
          type: integer
          format: int64
          description: The number of seconds that the session token will be valid
          example: '600'
          minimum: 0
        id_token:
          type: string
          description: Security token that must be passed in subsequent requests in order to authenticate the users
          example: v4.public.eyJqdGkiOiI3…
        otp_authorization_uri:
          type:
          - string
          - 'null'
          description: The uri that needs to be called from a mobile device in order to initiate the OTP flow. This appears only if the configured scope contains otp and the device can call otp_authoization_uri if the Silent Authentication has not been completed (i.e. timed out).
          example: https://auth-staging-api.tmtanalysis.com/v1/authenticate/otp?id_token=v4.public.eyJqdGkiOiI3ODExNDc5YS1lZjY1LT
  securitySchemes:
    basic:
      type: http
      scheme: basic
    paseto_token:
      type: http
      scheme: bearer
x-tagGroups:
- name: Introduction
  tags:
  - About TMT
- name: Service Specifications
  tags:
  - Authenticate
  - Service