swagger: "2.0"

info:
  title: mautrix-telegram provisioning
  version: 0.3.0
  description: The provisioning API for mautrix-telegram.
  contact:
    name: Tulir Asokan
    email: tulir@maunium.net
    url: https://maunium.net
  license:
    name: AGPLv3
    url: https://github.com/tulir/mautrix-telegram/blob/master/LICENSE

externalDocs:
  description: Provisioning API wiki page on GitHub.
  url: https://github.com/tulir/mautrix-telegram/wiki/Provisioning-API

basePath: /_matrix/provision

schemes: [https]
consumes: [application/json]
produces: [application/json]

tags:
- name: Authentication

paths:
  /{mxid}/get_me:
    get:
      operationId: get_me
      summary: Get the info of the Telegram user the given Matrix user is logged in as
      tags: [Authentication]
      responses:
        200:
          description: User is logged in
          schema:
            $ref: "#/definitions/AuthInfo"
        400:
          $ref: "#/responses/MissingMXIDError"
        403:
          description: User is not logged in or not whitelisted
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                enum:
                - not_logged_in
                - mxid_not_whitelisted
              error:
                $ref: "#/definitions/HumanReadableError"
        500:
          $ref: "#/responses/UnknownError"
      parameters:
        - name: mxid
          in: path
          description: The Matrix ID of the user who to log in as
          required: true
          type: string
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              token:
                type: string
                description: The access token of the bot to log in as
                example: "297900271:IXjeGEcAN61zHnjPgkWnYWyvVp9K4ulHBEv"
  /login/{mxid}/bot_token:
    post:
      operationId: post_bot_token
      summary: Log in with a bot token
      tags: [Authentication]
      responses:
        200:
          description: Login successful
          schema:
            $ref: "#/definitions/AuthSuccess"
        400:
          $ref: "#/responses/MissingMXIDError"
        401:
          description: Invalid or expired bot token or invalid shared secret
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                example: bot_token_<error>
                enum:
                - bot_token_invalid
                - bot_token_expired
                - shared_secret_invalid
              error:
                $ref: "#/definitions/HumanReadableError"
        403:
          $ref: "#/responses/NotWhitelistedError"
        409:
          $ref: "#/responses/AlreadyLoggedInError"
        500:
          $ref: "#/responses/UnknownError"
      parameters:
        - name: mxid
          in: path
          description: The Matrix ID of the user who to log in as
          required: true
          type: string
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              token:
                type: string
                description: The access token of the bot to log in as
                example: "297900271:IXjeGEcAN61zHnjPgkWnYWyvVp9K4ulHBEv"
  /login/{mxid}/request_code:
    post:
      operationId: post_login_phone
      summary: Request a phone code from Telegram
      tags: [Authentication]
      responses:
        200:
          description: Code requested successfully
          schema:
            $ref: "#/definitions/AuthSuccess"
        400:
          description: Invalid phone number or JSON or missing Matrix ID
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                example: machine_readable_error
                enum:
                - phone_number_invalid
                - mxid_empty
                - json_invalid
              error:
                $ref: "#/definitions/HumanReadableError"
        401:
          description: Invalid shared secret
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                enum:
                - shared_secret_invalid
              error:
                $ref: "#/definitions/HumanReadableError"
        403:
          description: Matrix ID is not whitelisted or phone number is banned or has forbidden 3rd party apps
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                example: machine_readable_error
                enum:
                - mxid_not_whitelisted
                - phone_number_banned
                - phone_number_app_signup_forbidden
              error:
                $ref: "#/definitions/HumanReadableError"
        404:
          description: Unregistered phone number
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                enum:
                - phone_number_unoccupied
              error:
                $ref: "#/definitions/HumanReadableError"
        409:
          $ref: "#/responses/AlreadyLoggedInError"
        429:
          description: Phone number has been temporarily blocked for flooding
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                enum:
                - flood_wait
                - phone_number_flood
              error:
                $ref: "#/definitions/HumanReadableError"
        500:
          $ref: "#/responses/UnknownError"
      parameters:
        - name: mxid
          in: path
          description: The Matrix ID of the user who to log in as
          required: true
          type: string
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              phone:
                type: string
                description: The phone number to log in as.
                example: "+123456789"
  /login/{mxid}/send_code:
    post:
      operationId: post_login_code
      summary: Send the login code
      tags: [Authentication]
      responses:
        200:
          description: Login successful
          schema:
            $ref: "#/definitions/AuthSuccess"
        202:
          description: Correct code, but two-factor authentication is enabled
          schema:
            $ref: "#/definitions/AuthSuccess"
        400:
          $ref: "#/responses/MissingMXIDError"
        401:
          description: Invalid phone code or shared secret
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                enum:
                - phone_code_invalid
                - shared_secret_invalid
              error:
                $ref: "#/definitions/HumanReadableError"
        403:
          description: Matrix ID not whitelisted or phone code expired
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                example: machine_readable_error
                enum:
                - mxid_not_whitelisted
                - phone_code_expired
              error:
                $ref: "#/definitions/HumanReadableError"
        409:
          $ref: "#/responses/AlreadyLoggedInError"
        500:
          $ref: "#/responses/UnknownError"
      parameters:
        - name: mxid
          in: path
          description: The Matrix ID of the user who to log in as
          required: true
          type: string
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              code:
                type: integer
                description: The phone code from Telegram.
                format: int32
                example: 123456
  /login/{mxid}/send_password:
    post:
      operationId: post_login_password
      summary: Send the two-factor auth password
      tags: [Authentication]
      responses:
        200:
          description: Login successful
          schema:
            $ref: "#/definitions/AuthSuccess"
        400:
          description: Missing password or Matrix ID or invalid JSON
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                example: <field>_empty
                enum:
                - password_empty
                - mxid_empty
                - json_invalid
              error:
                $ref: "#/definitions/HumanReadableError"
        401:
          description: Incorrect password or invalid shared secret
          schema:
            type: object
            title: Error
            properties:
              errcode:
                type: string
                title: Error code
                description: A machine-readable error code
                enum:
                - password_invalid
                - shared_secret_invalid
              error:
                $ref: "#/definitions/HumanReadableError"
        403:
          $ref: "#/responses/NotWhitelistedError"
        409:
          $ref: "#/responses/AlreadyLoggedInError"
        500:
          $ref: "#/responses/UnknownError"
      parameters:
        - name: mxid
          in: path
          description: The Matrix ID of the user who to log in as
          required: true
          type: string
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              password:
                type: string
                description: The two-factor auth password
                format: password
                example: hunter2

responses:
  NotWhitelistedError:
    description: Matrix ID not whitelisted for puppeting
    schema:
      type: object
      title: Error
      properties:
        errcode:
          type: string
          title: Error code
          description: A machine-readable error code
          enum:
          - mxid_not_whitelisted
        error:
          $ref: "#/definitions/HumanReadableError"
  AlreadyLoggedInError:
    description: The Matrix user is already logged in
    schema:
      type: object
      properties:
        state:
          type: string
          enum:
          - logged-in
        username:
          type: string
          description: The Telegram username the user is logged in as.
  MissingMXIDError:
    description: Missing Matrix ID or invalid JSON.
    schema:
      type: object
      title: Error
      properties:
        errcode:
          type: string
          title: Error code
          description: A machine-readable error code
          enum:
          - mxid_empty
          - json_invalid
        error:
          $ref: "#/definitions/HumanReadableError"
  UnknownError:
    description: Unknown error
    schema:
      type: object
      title: UnknownError
      properties:
        errcode:
          type: string
          title: Error code
          description: A machine-readable error code
          enum:
          - exception
        error:
          type: string
          title: Error
          description: A human-readable description of the error
          example: Internal server error while <action>.
          enum:
          - Internal server error while requesting code.
          - Internal server error while sending code.
          - Internal server error while sending password.
          - Internal server error while sending token.

definitions:
  HumanReadableError:
    type: string
    description: A human-readable description of the error
    example: A human-readable description of the error
  AuthInfo:
    type: object
    properties:
      username:
        type: string
        example: username
      first_name:
        type: string
        example: Usern
      last_name:
        type: string
        example: A.
      phone:
        type: string
        example: +123456789
      is_bot:
        type: boolean
        example: false

  AuthSuccess:
    type: object
    properties:
      state:
        type: string
        description: The state/next step after the successful operation.
        enum:
        - code
        - request
        - password
        - token
        - logged-in
      username:
        type: string
        description: The Telegram username the user is logged in as. Only applicable if state=logged-in


security:
  - Bearer: []
securityDefinitions:
  Bearer:
    description: Required authentication for all endpoints
    name: Authorization
    in: header
    type: apiKey