Tulir Asokan
480 lines
14 KiB
YAML
480 lines
14 KiB
YAML
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
|