Telstra Authentication API

openapi: 3.2.0
info:
  title: Telstra Authentication API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Authentication across 3 of this provider''s published API definitions: telstra-iot-connectivity-service-api-openapi.json, telstra-messaging-api-openapi.json, telstra-messaging-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://products.api.telstra.com/messaging/v3
  description: Messaging API
- url: https://tapi.telstra.com/v2
  description: Production Server
tags:
- name: Authentication
paths:
  /v2/oauth/token:
    servers:
    - description: Production OKAPI2 to get tokens
      url: https://tapi.telstra.com
    post:
      tags:
      - Authentication
      summary: Generate OAuth2 token
      description: 'To generate an OAuth2 Authentication token, pass through your `Client key` and `Client secret` that you received when you registered for the **API Free Trial** Product.

        The grant_type should be left as `client_credentials` and the scope as `NSMS`. The token will expire in one hour.'
      operationId: authToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - client_id
              - client_secret
              - grant_type
              properties:
                client_id:
                  type: string
                  description: ''
                client_secret:
                  type: string
                  description: ''
                grant_type:
                  type: string
                  default: client_credentials
                scope:
                  type: string
                  description: NSMS
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthResponse'
        '400':
          description: 'grant_type is incorrect. grant_type should be "client_credentials" (without quotes).

            Refer to the sample code for generate authentication token in the link for more details [https://dev.telstra.com/content/telstra-iot-connectivity-service-api#section/Authentication](https://dev.telstra.com/content/telstra-iot-connectivity-service-api#section/Authentication)

            '
          content: {}
        '401':
          description: 'Either client_id or client_secret or both are not valid.


            Ensure the client_id and client_secret matches with your keys.  Keys can be found under [https://dev.telstra.com/user/me/apps](https://dev.telstra.com/user/me/apps) and ensure there are no white spaces in client_id and client_secret

            '
          content: {}
        '404':
          description: 'The requested URI does not exist

            '
          content: {}
        '503':
          description: 'The service is currently unavailable.


            Please correct the API endpoint and try again. If the error persists even after re-try, check our [https://dev.telstra.com/api/status](https://dev.telstra.com/api/status) page to ensure the service is up and running.

            If the service is not up and running check our forum page [https://dev.telstra.com/telstradev-forum/icm-service-api-forum](https://dev.telstra.com/telstradev-forum/icm-service-api-forum) and leave a post to confirm the outage for the Telstradev admin to check the issue.

            '
          content: {}
        default:
          description: 'An internal error occurred when processing the request.


            If the error persists even after re-try, check our [https://dev.telstra.com/api/status](https://dev.telstra.com/api/status) page to ensure the service is up and running. If the service is not up and running check our forum page [https://dev.telstra.com/telstradev-forum/icm-service-api-forum](https://dev.telstra.com/telstradev-forum/icm-service-api-forum) and leave a post to confirm the outage for the Telstradev admin to check the issue.

            '
          content: {}
      x-code-samples:
      - lang: curl
        source: "#!/bin/bash\n# Obtain these keys from the Telstra Developer Portal\nCLIENT_KEY=\"your client key\"\nCLIENT_SECRET=\"your client secret\"\n\ncurl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \\\n-d 'grant_type=client_credentials&client_id=$CLIENT_KEY&client_secret=$CLIENT_SECRET&scope=NSMS' \\\n'https://tapi.telstra.com/v2/oauth/token'  \n"
  /oauth/token:
    post:
      description: 'To generate an OAuth2 Authentication token, pass through your `Client key` and `Client secret` that you received at Telstra Developer account.


        The value for grant_type is `client_credentials` and value for scope is `free-trial-numbers:read free-trial-numbers:write messages:read messages:write reports:read reports:write virtual-numbers:read virtual-numbers:write`.


        The token will expire in one hour.'
      summary: Generate OAuth2 token
      tags:
      - Authentication
      security:
      - {}
      servers:
      - url: https://products.api.telstra.com/v2
        description: OAuth2 server
      operationId: postOauthToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                grant_type:
                  type: string
                  default: client_credentials
                scope:
                  type: string
                  default: free-trial-numbers:read free-trial-numbers:write messages:read messages:write reports:read reports:write virtual-numbers:read virtual-numbers:write
              required:
              - client_id
              - client_secret
              - grant_type
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    description: OAuth access token
                    type: string
                  token_type:
                    description: OAuth token type
                    type: string
                  expires_in:
                    description: OAuth expiry time in seconds. Tokens expire in one hour.
                    type: string
        '400':
          description: '`grant_type` is incorrect. `grant_type` should be `client_credentials` (without quotes).

            Refer to generate authentication token tutorial in the link for more details https://dev.telstra.com/apis/messaging-api/tutorials/get-an-access-token

            '
        '401':
          description: 'Either client_id or client_secret or both are not valid.

            '
        '404':
          description: 'The requested URI does not exist

            '
        '503':
          description: 'The service is currently unavailable.

            '
        default:
          description: 'An internal error occurred when processing the request.


            If the error persists even after re-try, check out https://tdev.statuspage.io/ page to ensure the service is up and running.

            '
      x-codeSamples:
      - lang: curl
        source: '#!/bin/bash

          # Obtain these keys from the Telstra Developer Portal

          CLIENT_KEY="your client key"

          CLIENT_SECRET="your client secret"


          curl -X POST -H ''Content-Type: application/x-www-form-urlencoded'' \

          -d ''grant_type=client_credentials&client_id=$CLIENT_KEY&client_secret=$CLIENT_SECRET&scope=free-trial-numbers:read free-trial-numbers:write messages:read messages:write virtual-numbers:read virtual-numbers:write reports:read reports:write'' \

          ''https://products.api.telstra.com/v2/oauth/token''

          '
      x-operation-id-source: normalized
      x-operation-id-original: authToken
    servers:
    - url: https://products.api.telstra.com/messaging/v3
      description: Messaging API
components:
  schemas:
    OAuthResponse:
      title: OAuthResponse
      type: object
      properties:
        access_token:
          type: string
          description: OAuth access token
        token_type:
          type: string
          description: OAuth token type
        expires_in:
          type: string
          description: OAuth expiry time in seconds. Tokens expire in one hour.
    ErrorResponse:
      type: object
      required:
      - status
      - code
      - message
      properties:
        status:
          type: string
        code:
          type: string
        message:
          type: string
    OAuthTokenResponse:
      type: object
      required:
      - access_token
      - expires_in
      - token_type
      properties:
        access_token:
          type: string
          description: Bearer token for subsequent API calls.
        expires_in:
          type: string
          description: Token lifetime in seconds (commonly 3599).
        token_type:
          type: string
          enum:
          - Bearer
    OAuthTokenRequest:
      type: object
      required:
      - client_id
      - client_secret
      - grant_type
      properties:
        client_id:
          type: string
          description: The application's client ID issued by dev.telstra.com.
        client_secret:
          type: string
          description: The application's client secret.
        grant_type:
          type: string
          enum:
          - client_credentials
        scope:
          type: string
          default: NSMS
  responses:
    Unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    bearer_auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://products.api.telstra.com/v2/oauth/token
          scopes:
            free-trial-numbers:read: read information for free trial numbers
            free-trial-numbers:write: write information for free trial numbers
            messages:read: read information for messages
            messages:write: write information for messages
            reports:read: read information for reports
            reports:write: write information for reports
            virtual-numbers:read: read information for virtual-numbers
            virtual-numbers:write: write information for virtual numbers
    OAuth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 client credentials grant against https://tapi.telstra.com/v2/oauth/token with the NSMS scope.
      flows:
        clientCredentials:
          tokenUrl: https://tapi.telstra.com/v2/oauth/token
          scopes:
            NSMS: Send and receive SMS/MMS through Telstra Messaging.
x-refined-from:
- telstra-iot-connectivity-service-api-openapi.json
- telstra-messaging-api-openapi.json
- telstra-messaging-api-openapi.yml