TMT Authenticate API

openapi: 3.0.3
info:
  title: TMT Authenticate API specs
  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
servers:
- url: https://auth-staging-api.tmtid.dev/v1
  description: Pre-Production
- url: https://auth-api.tmtanalysis.com/v1
  description: Production Server
schemes:
- https
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: []
  /authenticate:
    get:
      tags:
      - Service
      summary: Authenticate with Silent Network Authentication method
      description: 'Authenticate with Silent Network Authentication method


        The authenticate endpoint will execute the Silent Authentication against the Operator wherever this is supported.'
      operationId: authenticateUserWithMNO
      parameters:
      - name: id_token
        in: query
        description: Provided in the get_config request
        required: true
        schema:
          type: string
        example: v4.public.eyJuZXR3b3JrIjoiVk9EQUZPTkUiLCJ1c2VyX2lkIjoiZDFmYTA2ZDQtOTM1My0xMWVkLTgzZWQtNGY4ZGVjMDc1ZWM4IiwibmJmIjoiMjAyMy0w...
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallBackResponse'
        '302':
          description: ''
          content:
            application/json:
              schema:
                type: string
              examples:
                Ok:
                  description: Response with RedirectUri
                  value: https://example.com/callback?code=f3c75c82-9f85-42ab-be67-36f9dceb891e&correlation_id=123456789
        '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 Scope:
                  description: Session token does not contain authenticate scope
                  value:
                    error: invalid_scope
                    error_description: The requested scope is invalid, unknown or malformed.
                Invalid Token:
                  description: Session token does not contain redirect_uri claim.
                  value:
                    error: invalid_request
                    error_description: The provided token is invalid.
  /authenticate/otp:
    get:
      tags:
      - Service
      summary: Authenticate with  One-Time Password method
      description: 'Authenticate with  One-Time Password method


        This specific endpoint will be triggered by the Customer and in case of success a special form where the user needs to input the OTP code needs to be displayed in the Customer APP.'
      operationId: authenticateUserWithOtp
      parameters:
      - name: id_token
        in: query
        description: Provided in the get_config request
        required: true
        schema:
          type: string
        example: v4.public.eyJuZXR3b3JrIjoiVk9EQUZPTkUiLCJ1c2VyX2lkIjoiZDFmYTA2ZDQtOTM1My0xMWVkLTgzZWQtNGY4ZGVjMDc1ZWM4IiwibmJmIjoiMjAyMy0w...
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallBackResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request:
                  description: Maximum number of times a user can request the OTP was exceeded!
                  value:
                    error: invalid_request
                    error_description: The required field is missing or it is invalid.
                Exceeded Attempts:
                  description: Maximum number of times a user can request the OTP was exceeded
                  value:
                    error: invalid_request
                    error_description: Exceeded maximum number of retry attempts.
                Invalid Code:
                  description: Error parsing the payload received
                  value:
                    error: invalid_code
                    error_description: The requested code is invalid, unknown or malformed.
                Invalid Scope:
                  description: 'Session token does not contain ''otp'' scope.


                    Session token does not cointain ''authenticate'' scope.'
                  value:
                    error: invalid_scope
                    error_description: The requested scope is invalid, unknown or malformed.
                Invalid Status:
                  description: Session token was used to authenticate and otp in less than 5 seconds.
                  value:
                    error: invalid scope
                    error_description: OTP requested before Authenticate
                Invalid Token:
                  description: 'Session token does not contain claims.


                    Vendor name is missing from the token


                    Vendor name could not be parsed from the token


                    '
                  value:
                    error: invalid_request
                    error_description: The provided token is invalid
                Retry Attempt:
                  description: Session token was used to authenticate and otp in less than {} seconds
                  value:
                    error: invalid_request
                    error_description: You have to wait a few second before trying to get otp sms again
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Service Unavailable:
                  description: Sending OTP code failed
                  value:
                    error: temporarily_unavailable
                    error_description: Service is unavailable
components:
  schemas:
    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
    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
    AuthenticateQuery:
      type: object
      required:
      - id_token
      properties:
        id_token:
          type: string
          description: Provided in the get_config request
    AuthorizationUri:
      type: object
      required:
      - id_token
      - expires_in
      properties:
        authorize:
          allOf:
          - $ref: '#/components/schemas/AuthorizeRequestConfig'
          nullable: true
        correlation_id:
          type: string
          description: Provided only if the correlation_id parameter was  submitted through in the /get_config request.
          example: Noo7siol1Yj763XTRDidILTv96ly9kFS
          nullable: true
        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
          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
          nullable: true
    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'
            nullable: true
          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'
    CallBackResponse:
      type: object
      required:
      - session_id
      properties:
        session_id:
          type: string
          description: A session_id of the current user.
          example: pYXQiOiIyMDIyLTEyLTEyVDEyOjI4Oj
    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
          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
          nullable: true
        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
          description: Predefined callback url to be used in the session and send the request back to the client
          nullable: true
    GetResult:
      type: object
      required:
      - id_token
      properties:
        code:
          type: string
          description: Code obtained from the authenticate request on redirect_uri
          example: 64a5b19-457a-4d30-a5c4-038c62dcssfg3
          nullable: true
        correlation_id:
          type: string
          description: The correlation_id submitted through the get_config request
          example: Noo7siol1Yj763XTRDidILTv96ly9kFS
          nullable: true
        id_token:
          type: string
          description: Provided in the get_config request
          example: v4.public.eyJ2ZW5kb3JfdHlwZSI6IkVFIiwianRp…
        otp_code:
          type: string
          description: Provided only if we need to validate the user using the OTP service
          example: '123456'
          nullable: true
        payload:
          description: JSON Response obtained from the authenticate or otp request.
          nullable: true
    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
          example: Noo7siol1Yj763XTRDidILTv96ly9kFS
          nullable: true
        service:
          type: string
          description: Value authenticate or otp depending on the type of authentication mechanism used
          example: authenticate
    VendorAuthorizationConfig:
      type: object
      properties:
        headers:
          type: object
          additionalProperties:
            type: string
          nullable: true
        parameters:
          type: object
          additionalProperties:
            type: string
          nullable: true
  securitySchemes:
    basic:
      type: http
      scheme: basic
    paseto_token:
      type: http
      scheme: bearer
tags:
- description: '

    TMT ID is a leading provider of data, intelligence and analytics, helping customers find extra value from the information they hold. Our team of technology and telecommunications specialists has a proven track record empowering companies, brands and agencies around the world to better understand their businesses and their customers. TMT ID has a suite of technology and telecommunications data available, for further information, please visit [www.tmtid.com](https://www.tmtid.com) or email info@tmtid.com.'
  name: About TMT
- name: Authenticate
  description: Authenticate user with MNO or OTP. These endpoints can be directly called by the users.
- name: Service
  description: Service endpoints
x-tagGroups:
- name: Introduction
  tags:
  - About TMT
- name: Service Specifications
  tags:
  - Authenticate
  - Service