Telesign Protect API Authentication API

openapi: 3.2.0
info:
  title: Protect Platform Protect API Authentication API
  version: '1.0'
  description: Use this API to initiate authentication for the Protect Platform API.
  contact:
    name: Telesign Customer Support Team
    email: support@telesign.com
servers:
- url: https://us-east-1.di-platform.telesign.com
tags:
- name: Protect API Authentication
paths:
  /authenticationmanager/v1/authenticate/api:
    parameters: []
    post:
      summary: Generate access token
      operationId: initiateAuthentication
      responses:
        '200':
          description: '**Success.** The request was processed successfully.


            | Status | Condition | error.message | Description |

            | --- | --- | --- | --- |

            | Success | — | The request was processed successfully. |'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Describes the results of the authentication request.
                    example: Operation completed successfully.
                  data:
                    type: object
                    description: 'Contains properties related to the the access token. '
                    properties:
                      accessToken:
                        type: string
                        description: 'Access token to be used in `Authorization: Bearer`. Must be used in all subsequent API requests.'
                        example: YOUR_ACCESS_TOKEN_HERE
                      expirationTimeSeconds:
                        type: integer
                        description: 'The validity of the token, measured in seconds. '
                        example: 28800
              examples:
                Response:
                  value:
                    message: Operation completed successfully.
                    data:
                      accessToken: YOUR_ACCESS_TOKEN_HERE
                      expirationTimeSeconds: 28800
        '400':
          description: "**Request validation failed.** One or more fields are missing or have the wrong type/format. See `errors.description` for more details.\n\nStatus Condition | error.message  | Description\n------------|---------------------|------------------------------\nMalformed JSON/body fields  | `Request validation failed`         | One or more fields are missing or have the wrong type/format. See `errors.description` for a per-field breakdown.                                           \n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokenResponse'
              examples:
                Validation errors:
                  value:
                    errors:
                    - name: The authorization field is required.
                      description: One or more validation errors occurred.
        '401':
          description: "**Authorization Errors.** The authentication request failed because the token was invalid, expired, couldn't be validated or because no authorization header was provided. \n\nStatus Condition | error.message  | Description\n------------|---------------------|------------------------------\nToken failed validation  | Error validating token         | Token could not be parsed or verified.                                           \nProduct failed validation | Error validating token access to product | Credentials have no access to the product.                                                           \nNo Authorization header | No authorization header provided | Authentication header is completely absent.  \nToken expired / not found | Invalid or expired token | Token is syntactically valid but expired or no longer accepted."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokenResponse'
              examples:
                Incorrect API key:
                  value:
                    errors:
                    - name: Unauthorized
                      description: Incorrect api key
                Invalid authorization header:
                  value:
                    errors:
                    - name: Unauthorized
                      description: Invalid authorization header
                Invalid credentials:
                  value:
                    errors:
                    - name: Unauthorized
                      description: API Credentials do not exist, check that credentials are suitable for this product
        '404':
          description: '**Unknown path.** The requested resource or endpoint does not exist. Invalid Path or endpoint requested, the API returns an error.


            Status Condition | error.message  | Description

            ------------|---------------------|----------------

            Unknown path | `Endpoint not found` | The requested resource or endpoint does not exist.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokenResponse'
              examples:
                Endpoint not found:
                  value:
                    errors:
                    - name: Unknown path
                      description: The requested resource or endpoint does not exist
        '500':
          description: '**Internal error.** Unexpected exception on the server side.


            Status Condition | error.message  | Description

            ------------|---------------------|----------------

            Internal error | Internal Server Error | Unexpected exception on the server side.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tokenResponse'
              examples:
                Internal server error:
                  value:
                    errors:
                    - name: Internal Server Error
                      description: Unexpected exception on the server side
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                productId:
                  type: integer
                  default: 3
                  description: The Product ID associated with the Flow Builder. The Product Id for the Flow Builder is `3`.
            examples:
              Authentication request:
                value:
                  productId: 3
        description: ''
      description: '> 📘 NOTE:

        >

        > Select regional availability. This feature is currently available for customers with end users in select countries. To find out if this feature is available in your region, contact a Telesign expert. This product is available for full-service accounts only.


        Use this endpoint to generate an access token to interact securely with Protect Platform services, which require an external authentication service that issues an access token upon successful validation of an API Key.


        Send credentials via Basic Auth ("Authorization: Basic ...") together with "x-API-key". After you send a POST request to the authentication service with the required credentials, the service returns a Bearer token, which must be included in the Authorization header of all subsequent API requests to ensure secure access. If your access token expires, you must re-authenticate using this endpoint to obtain a new token. Include the accessToken in the Authorization header of every API request for authentication and authorization.


        ## General requirements

        * **Authentication:** [Basic]

        * **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.

        * **Accepts:** `application/json`

        * **Responds with:** `application/json`

        * **Required headers:**

        * `Content-Type: application/json`

        * `x-API-key: [YOUR_API_KEY_HERE]`'
      parameters:
      - schema:
          type: string
        in: header
        name: Authorization
        description: Your credentials encoded in Base64 (e.g., Basic YOUR_BASE64_ENCODED_CREDENTIALS)
        required: true
      - schema:
          type: string
        in: header
        name: x-API-key
        description: The API Key associated with your account. (e.g., YOUR_API_KEY_HERE)
        required: true
      - schema:
          type: string
        in: header
        name: Content-Type
        description: Must be set to application/json.
        required: true
      tags:
      - Protect API Authentication
components:
  schemas:
    tokenResponse:
      title: tokenResponse
      type: object
      x-examples: {}
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: The error returned by the API.
              description:
                type: string
                description: A description of an error returned by the API.
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true