openapi: 3.1.0
info:
  title: Telstra Messaging Authentication API
  description: 'The Telstra Messaging API provides programmatic SMS and MMS messaging

    services in Australia and select international destinations. Built on

    the Telstra mobile network, the API supports outbound and inbound

    SMS/MMS, delivery status callbacks, virtual numbers, and provisioning

    workflows. Authentication uses OAuth 2.0 client credentials with the

    NSMS scope.

    '
  version: 2.2.10
  contact:
    name: Telstra Developer Support
    url: https://dev.telstra.com
  termsOfService: https://www.telstra.com.au/business-enterprise/legal/messaging-api-terms-of-service
  license:
    name: Telstra Developer License
    url: https://github.com/telstra/tdev-doc-license
  x-logo:
    url: https://www.telstra.com.au/etc/designs/telstrav8/clientlibs/img/Telstra_Symbol.svg
servers:
- url: https://tapi.telstra.com/v2
  description: Production Server
security:
- OAuth2ClientCredentials:
  - NSMS
tags:
- name: Authentication
  description: OAuth 2.0 client credentials token issuance.
paths:
  /oauth/token:
    post:
      summary: Telstra Generate OAuth Token
      description: Generate an OAuth 2.0 bearer token using the client credentials grant with the NSMS scope.
      operationId: generateToken
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OAuthTokenRequest'
      responses:
        '200':
          description: Token issued successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    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
    ErrorResponse:
      type: object
      required:
      - status
      - code
      - message
      properties:
        status:
          type: string
        code:
          type: string
        message:
          type: string
    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:
    BadRequest:
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    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.