dandri/matrix-authentication-service
1
0
Fork 0
mirror of https://github.com/element-hq/matrix-authentication-service.git synced 2026-03-30 19:25:47 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
566bb07799b20a7024be42738bcfecb25ca2d45f
matrix-authentication-service/docs/api/spec.json
Quentin Gliech a35cb76c41 Remove the nullable transform
2025-11-07 10:53:46 +01:00

7450 lines
229 KiB
JSON
Raw Blame History

{
"openapi": "3.1.0",
"info": {
"title": "Matrix Authentication Service admin API",
"version": ""
},
"servers": [
{
"url": "{base}",
"variables": {
"base": {
"default": "/",
"description": null
}
}
}
],
"paths": {
"/api/admin/v1/site-config": {
"get": {
"tags": [
"server"
],
"summary": "Get informations about the configuration of this MAS instance",
"operationId": "siteConfig",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SiteConfig"
},
"example": {
"server_name": "example.com",
"password_login_enabled": true,
"password_registration_enabled": true,
"password_registration_email_required": true,
"registration_token_required": true,
"email_change_allowed": true,
"displayname_change_allowed": true,
"password_change_allowed": true,
"account_recovery_allowed": true,
"account_deactivation_allowed": true,
"captcha_enabled": true,
"minimum_password_complexity": 3
}
}
}
}
}
}
},
"/api/admin/v1/version": {
"get": {
"tags": [
"server"
],
"summary": "Get the version currently running",
"operationId": "version",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Version"
},
"example": {
"version": "v1.0.0"
}
}
}
}
}
}
},
"/api/admin/v1/compat-sessions": {
"get": {
"tags": [
"compat-session"
],
"summary": "List compatibility sessions",
"description": "Retrieve a list of compatibility sessions.\nNote that by default, all sessions, including finished ones are returned, with the oldest first.\nUse the `filter[status]` parameter to filter the sessions by their status and `page[last]` parameter to retrieve the last N sessions.",
"operationId": "listCompatSessions",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "count",
"description": "Include the total number of items. Defaults to `true`.",
"schema": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[user]",
"description": "Retrieve the items for the given user",
"schema": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[user-session]",
"description": "Retrieve the items started from the given browser session",
"schema": {
"description": "Retrieve the items started from the given browser session",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[status]",
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all sessions, including finished ones.\n\n * `active`: Only retrieve active sessions\n\n * `finished`: Only retrieve finished sessions",
"schema": {
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all sessions, including finished ones.\n\n * `active`: Only retrieve active sessions\n\n * `finished`: Only retrieve finished sessions",
"anyOf": [
{
"$ref": "#/components/schemas/CompatSessionStatus"
},
{
"type": "null"
}
]
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of compatibility sessions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_CompatSession"
},
"example": {
"meta": {
"count": 42
},
"data": [
{
"type": "compat-session",
"id": "01040G2081040G2081040G2081",
"attributes": {
"user_id": "01040G2081040G2081040G2081",
"device_id": "AABBCCDDEE",
"user_session_id": "0H248H248H248H248H248H248H",
"redirect_uri": "https://example.com/redirect",
"created_at": "1970-01-01T00:00:00Z",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "1.2.3.4",
"finished_at": null,
"human_name": "Laptop"
},
"links": {
"self": "/api/admin/v1/compat-sessions/01040G2081040G2081040G2081"
},
"meta": {
"page": {
"cursor": "01040G2081040G2081040G2081"
}
}
},
{
"type": "compat-session",
"id": "02081040G2081040G2081040G2",
"attributes": {
"user_id": "01040G2081040G2081040G2081",
"device_id": "FFGGHHIIJJ",
"user_session_id": "0J289144GJ289144GJ289144GJ",
"redirect_uri": null,
"created_at": "1970-01-01T00:00:00Z",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "1.2.3.4",
"finished_at": "1970-01-01T00:00:00Z",
"human_name": null
},
"links": {
"self": "/api/admin/v1/compat-sessions/02081040G2081040G2081040G2"
},
"meta": {
"page": {
"cursor": "02081040G2081040G2081040G2"
}
}
},
{
"type": "compat-session",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"user_id": "01040G2081040G2081040G2081",
"device_id": null,
"user_session_id": null,
"redirect_uri": null,
"created_at": "1970-01-01T00:00:00Z",
"user_agent": null,
"last_active_at": null,
"last_active_ip": null,
"finished_at": null,
"human_name": null
},
"links": {
"self": "/api/admin/v1/compat-sessions/030C1G60R30C1G60R30C1G60R3"
},
"meta": {
"page": {
"cursor": "030C1G60R30C1G60R30C1G60R3"
}
}
}
],
"links": {
"self": "/api/admin/v1/compat-sessions?page[first]=3",
"first": "/api/admin/v1/compat-sessions?page[first]=3",
"last": "/api/admin/v1/compat-sessions?page[last]=3",
"next": "/api/admin/v1/compat-sessions?page[after]=030C1G60R30C1G60R30C1G60R3&page[first]=3"
}
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/compat-sessions/{id}": {
"get": {
"tags": [
"compat-session"
],
"summary": "Get a compatibility session",
"operationId": "getCompatSession",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "Compatibility session was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_CompatSession"
},
"example": {
"data": {
"type": "compat-session",
"id": "01040G2081040G2081040G2081",
"attributes": {
"user_id": "01040G2081040G2081040G2081",
"device_id": "AABBCCDDEE",
"user_session_id": "0H248H248H248H248H248H248H",
"redirect_uri": "https://example.com/redirect",
"created_at": "1970-01-01T00:00:00Z",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "1.2.3.4",
"finished_at": null,
"human_name": "Laptop"
},
"links": {
"self": "/api/admin/v1/compat-sessions/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/compat-sessions/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "Compatibility session was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Compatibility session ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/compat-sessions/{id}/finish": {
"post": {
"tags": [
"compat-session"
],
"summary": "Finish a compatibility session",
"description": "Calling this endpoint will finish the compatibility session, preventing any further use. A job will be scheduled to sync the user's devices with the homeserver.",
"operationId": "finishCompatSession",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "Compatibility session was finished",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_CompatSession"
},
"example": {
"data": {
"type": "compat-session",
"id": "02081040G2081040G2081040G2",
"attributes": {
"user_id": "01040G2081040G2081040G2081",
"device_id": "FFGGHHIIJJ",
"user_session_id": "0J289144GJ289144GJ289144GJ",
"redirect_uri": null,
"created_at": "1970-01-01T00:00:00Z",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "1.2.3.4",
"finished_at": "1970-01-01T00:00:00Z",
"human_name": null
},
"links": {
"self": "/api/admin/v1/compat-sessions/02081040G2081040G2081040G2"
}
},
"links": {
"self": "/api/admin/v1/compat-sessions/02081040G2081040G2081040G2/finish"
}
}
}
}
},
"400": {
"description": "Session is already finished",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Compatibility session with ID 00000000000000000000000000 is already finished"
}
]
}
}
}
},
"404": {
"description": "Compatibility session was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Compatibility session with ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/oauth2-sessions": {
"get": {
"tags": [
"oauth2-session"
],
"summary": "List OAuth 2.0 sessions",
"description": "Retrieve a list of OAuth 2.0 sessions.\nNote that by default, all sessions, including finished ones are returned, with the oldest first.\nUse the `filter[status]` parameter to filter the sessions by their status and `page[last]` parameter to retrieve the last N sessions.",
"operationId": "listOAuth2Sessions",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "count",
"description": "Include the total number of items. Defaults to `true`.",
"schema": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[user]",
"description": "Retrieve the items for the given user",
"schema": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[client]",
"description": "Retrieve the items for the given client",
"schema": {
"description": "Retrieve the items for the given client",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[client-kind]",
"description": "Retrieve the items only for a specific client kind",
"schema": {
"description": "Retrieve the items only for a specific client kind",
"anyOf": [
{
"$ref": "#/components/schemas/OAuth2ClientKind"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[user-session]",
"description": "Retrieve the items started from the given browser session",
"schema": {
"description": "Retrieve the items started from the given browser session",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[scope]",
"description": "Retrieve the items with the given scope",
"schema": {
"description": "Retrieve the items with the given scope",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"style": "form"
},
{
"in": "query",
"name": "filter[status]",
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all sessions, including finished ones.\n\n * `active`: Only retrieve active sessions\n\n * `finished`: Only retrieve finished sessions",
"schema": {
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all sessions, including finished ones.\n\n * `active`: Only retrieve active sessions\n\n * `finished`: Only retrieve finished sessions",
"anyOf": [
{
"$ref": "#/components/schemas/OAuth2SessionStatus"
},
{
"type": "null"
}
]
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of OAuth 2.0 sessions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_OAuth2Session"
},
"example": {
"meta": {
"count": 42
},
"data": [
{
"type": "oauth2-session",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": null,
"user_id": "02081040G2081040G2081040G2",
"user_session_id": "030C1G60R30C1G60R30C1G60R3",
"client_id": "040G2081040G2081040G208104",
"scope": "openid",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1",
"human_name": "Laptop"
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/01040G2081040G2081040G2081"
},
"meta": {
"page": {
"cursor": "01040G2081040G2081040G2081"
}
}
},
{
"type": "oauth2-session",
"id": "02081040G2081040G2081040G2",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": null,
"user_id": null,
"user_session_id": null,
"client_id": "050M2GA1850M2GA1850M2GA185",
"scope": "urn:mas:admin",
"user_agent": null,
"last_active_at": null,
"last_active_ip": null,
"human_name": null
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/02081040G2081040G2081040G2"
},
"meta": {
"page": {
"cursor": "02081040G2081040G2081040G2"
}
}
},
{
"type": "oauth2-session",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": "1970-01-01T00:00:00Z",
"user_id": "040G2081040G2081040G208104",
"user_session_id": "050M2GA1850M2GA1850M2GA185",
"client_id": "060R30C1G60R30C1G60R30C1G6",
"scope": "urn:matrix:client:api:*",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1",
"human_name": null
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/030C1G60R30C1G60R30C1G60R3"
},
"meta": {
"page": {
"cursor": "030C1G60R30C1G60R30C1G60R3"
}
}
}
],
"links": {
"self": "/api/admin/v1/oauth2-sessions?page[first]=3",
"first": "/api/admin/v1/oauth2-sessions?page[first]=3",
"last": "/api/admin/v1/oauth2-sessions?page[last]=3",
"next": "/api/admin/v1/oauth2-sessions?page[after]=030C1G60R30C1G60R30C1G60R3&page[first]=3"
}
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
},
"400": {
"description": "Invalid scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Invalid scope \"not a valid scope\" in filter parameters"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/oauth2-sessions/{id}": {
"get": {
"tags": [
"oauth2-session"
],
"summary": "Get an OAuth 2.0 session",
"operationId": "getOAuth2Session",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "OAuth 2.0 session was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_OAuth2Session"
},
"example": {
"data": {
"type": "oauth2-session",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": null,
"user_id": "02081040G2081040G2081040G2",
"user_session_id": "030C1G60R30C1G60R30C1G60R3",
"client_id": "040G2081040G2081040G208104",
"scope": "openid",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1",
"human_name": "Laptop"
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "OAuth 2.0 session was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "OAuth 2.0 session ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/oauth2-sessions/{id}/finish": {
"post": {
"tags": [
"oauth2-session"
],
"summary": "Finish an OAuth 2.0 session",
"description": "Calling this endpoint will finish the OAuth 2.0 session, preventing any further use. If the session has a user associated with it, a job will be scheduled to sync the user's devices with the homeserver.",
"operationId": "finishOAuth2Session",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "OAuth 2.0 session was finished",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_OAuth2Session"
},
"example": {
"data": {
"type": "oauth2-session",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": "1970-01-01T00:00:00Z",
"user_id": "040G2081040G2081040G208104",
"user_session_id": "050M2GA1850M2GA1850M2GA185",
"client_id": "060R30C1G60R30C1G60R30C1G6",
"scope": "urn:matrix:client:api:*",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1",
"human_name": null
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/030C1G60R30C1G60R30C1G60R3"
}
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/030C1G60R30C1G60R30C1G60R3/finish"
}
}
}
}
},
"400": {
"description": "Session is already finished",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "OAuth 2.0 session with ID 00000000000000000000000000 is already finished"
}
]
}
}
}
},
"404": {
"description": "OAuth 2.0 session was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "OAuth 2.0 session with ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/personal-sessions": {
"get": {
"tags": [
"personal-session"
],
"summary": "List personal sessions",
"description": "Retrieve a list of personal sessions.\nNote that by default, all sessions, including revoked ones are returned, with the oldest first.\nUse the `filter[status]` parameter to filter the sessions by their status and `page[last]` parameter to retrieve the last N sessions.",
"operationId": "listPersonalSessions",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "count",
"description": "Include the total number of items. Defaults to `true`.",
"schema": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[owner_user]",
"description": "Filter by owner user ID",
"schema": {
"description": "Filter by owner user ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[owner_client]",
"description": "Filter by owner `OAuth2` client ID",
"schema": {
"description": "Filter by owner `OAuth2` client ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[actor_user]",
"description": "Filter by actor user ID",
"schema": {
"description": "Filter by actor user ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[scope]",
"description": "Retrieve the items with the given scope",
"schema": {
"description": "Retrieve the items with the given scope",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"style": "form"
},
{
"in": "query",
"name": "filter[status]",
"description": "Filter by session status",
"schema": {
"description": "Filter by session status",
"anyOf": [
{
"$ref": "#/components/schemas/PersonalSessionStatus"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[expires_before]",
"description": "Filter by access token expiry date",
"schema": {
"description": "Filter by access token expiry date",
"type": [
"string",
"null"
],
"format": "date-time"
},
"style": "form"
},
{
"in": "query",
"name": "filter[expires_after]",
"description": "Filter by access token expiry date",
"schema": {
"description": "Filter by access token expiry date",
"type": [
"string",
"null"
],
"format": "date-time"
},
"style": "form"
},
{
"in": "query",
"name": "filter[expires]",
"description": "Filter by whether the access token has an expiry time",
"schema": {
"description": "Filter by whether the access token has an expiry time",
"type": [
"boolean",
"null"
]
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of personal sessions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_PersonalSession"
},
"example": {
"meta": {
"count": 3
},
"data": [
{
"type": "personal-session",
"id": "01FSHN9AG0AJ6AC5HQ9X6H4RP4",
"attributes": {
"created_at": "2022-01-16T13:00:00Z",
"revoked_at": null,
"owner_user_id": "01FSHN9AG0MZAA6S4AF7CTV32E",
"owner_client_id": null,
"actor_user_id": "01FSHN9AG0MZAA6S4AF7CTV32E",
"human_name": "Alice's Development Token",
"scope": "openid urn:matrix:org.matrix.msc2967.client:api:*",
"last_active_at": "2022-01-16T15:30:00Z",
"last_active_ip": "192.168.1.100",
"expires_at": null
},
"links": {
"self": "/api/admin/v1/personal-sessions/01FSHN9AG0AJ6AC5HQ9X6H4RP4"
},
"meta": {
"page": {
"cursor": "01FSHN9AG0AJ6AC5HQ9X6H4RP4"
}
}
},
{
"type": "personal-session",
"id": "01FSHN9AG0BJ6AC5HQ9X6H4RP5",
"attributes": {
"created_at": "2022-01-16T13:01:00Z",
"revoked_at": "2022-01-16T16:20:00Z",
"owner_user_id": "01FSHN9AG0NZAA6S4AF7CTV32F",
"owner_client_id": null,
"actor_user_id": "01FSHN9AG0NZAA6S4AF7CTV32F",
"human_name": "Bob's Mobile App",
"scope": "openid",
"last_active_at": "2022-01-16T16:03:20Z",
"last_active_ip": "10.0.0.50",
"expires_at": null
},
"links": {
"self": "/api/admin/v1/personal-sessions/01FSHN9AG0BJ6AC5HQ9X6H4RP5"
},
"meta": {
"page": {
"cursor": "01FSHN9AG0BJ6AC5HQ9X6H4RP5"
}
}
},
{
"type": "personal-session",
"id": "01FSHN9AG0CJ6AC5HQ9X6H4RP6",
"attributes": {
"created_at": "2022-01-16T13:02:00Z",
"revoked_at": null,
"owner_user_id": null,
"owner_client_id": "01FSHN9AG0DJ6AC5HQ9X6H4RP7",
"actor_user_id": "01FSHN9AG0MZAA6S4AF7CTV32E",
"human_name": "CI/CD Pipeline Token",
"scope": "openid urn:mas:admin",
"last_active_at": "2022-01-16T15:46:40Z",
"last_active_ip": "203.0.113.10",
"expires_at": "2022-01-24T04:36:40Z"
},
"links": {
"self": "/api/admin/v1/personal-sessions/01FSHN9AG0CJ6AC5HQ9X6H4RP6"
},
"meta": {
"page": {
"cursor": "01FSHN9AG0CJ6AC5HQ9X6H4RP6"
}
}
}
],
"links": {
"self": "/api/admin/v1/personal-sessions?page[first]=3",
"first": "/api/admin/v1/personal-sessions?page[first]=3",
"last": "/api/admin/v1/personal-sessions?page[last]=3",
"next": "/api/admin/v1/personal-sessions?page[after]=01FSHN9AG0CJ6AC5HQ9X6H4RP6&page[first]=3"
}
}
}
}
},
"404": {
"description": "Client was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Client ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
},
"post": {
"tags": [
"personal-session"
],
"summary": "Create a new personal session with personal access token",
"operationId": "createPersonalSession",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePersonalSessionRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Personal session and personal access token were created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_PersonalSession"
}
}
}
},
"400": {
"description": "Invalid scope provided",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Invalid scope"
}
]
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/personal-sessions/{id}": {
"get": {
"tags": [
"personal-session"
],
"summary": "Get a personal session",
"operationId": "getPersonalSession",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "Personal session details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_PersonalSession"
},
"example": {
"data": {
"type": "personal-session",
"id": "01FSHN9AG0AJ6AC5HQ9X6H4RP4",
"attributes": {
"created_at": "2022-01-16T13:00:00Z",
"revoked_at": null,
"owner_user_id": "01FSHN9AG0MZAA6S4AF7CTV32E",
"owner_client_id": null,
"actor_user_id": "01FSHN9AG0MZAA6S4AF7CTV32E",
"human_name": "Alice's Development Token",
"scope": "openid urn:matrix:org.matrix.msc2967.client:api:*",
"last_active_at": "2022-01-16T15:30:00Z",
"last_active_ip": "192.168.1.100",
"expires_at": null
},
"links": {
"self": "/api/admin/v1/personal-sessions/01FSHN9AG0AJ6AC5HQ9X6H4RP4"
}
},
"links": {
"self": "/api/admin/v1/personal-sessions/01FSHN9AG0AJ6AC5HQ9X6H4RP4"
}
}
}
}
},
"404": {
"description": "Personal session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Personal session not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/personal-sessions/{id}/revoke": {
"post": {
"tags": [
"personal-session"
],
"summary": "Revoke a personal session",
"operationId": "revokePersonalSession",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "Personal session was revoked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_PersonalSession"
},
"example": {
"data": {
"type": "personal-session",
"id": "01FSHN9AG0AJ6AC5HQ9X6H4RP4",
"attributes": {
"created_at": "2022-01-16T13:00:00Z",
"revoked_at": null,
"owner_user_id": "01FSHN9AG0MZAA6S4AF7CTV32E",
"owner_client_id": null,
"actor_user_id": "01FSHN9AG0MZAA6S4AF7CTV32E",
"human_name": "Alice's Development Token",
"scope": "openid urn:matrix:org.matrix.msc2967.client:api:*",
"last_active_at": "2022-01-16T15:30:00Z",
"last_active_ip": "192.168.1.100",
"expires_at": null
},
"links": {
"self": "/api/admin/v1/personal-sessions/01FSHN9AG0AJ6AC5HQ9X6H4RP4"
}
},
"links": {
"self": "/api/admin/v1/personal-sessions/01FSHN9AG0AJ6AC5HQ9X6H4RP4"
}
}
}
}
},
"404": {
"description": "Personal session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Personal session with ID 00000000000000000000000000 not found"
}
]
}
}
}
},
"409": {
"description": "Personal session already revoked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Personal session with ID 00000000000000000000000000 is already revoked"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/personal-sessions/{id}/regenerate": {
"post": {
"tags": [
"personal-session"
],
"summary": "Regenerate a personal session by replacing its personal access token",
"operationId": "regeneratePersonalSession",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegeneratePersonalSessionRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Personal session was regenerated and a personal access token was created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_PersonalSession"
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/policy-data": {
"post": {
"tags": [
"policy-data"
],
"summary": "Set the current policy data",
"operationId": "setPolicyData",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetPolicyDataRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Policy data was successfully set",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_PolicyData"
},
"example": {
"data": {
"type": "policy-data",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"data": {
"hello": "world",
"foo": 42,
"bar": true
}
},
"links": {
"self": "/api/admin/v1/policy-data/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/policy-data/01040G2081040G2081040G2081"
}
}
}
}
},
"400": {
"description": "Invalid policy data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Failed to instanciate policy with the provided data"
},
{
"title": "invalid policy data"
},
{
"title": "Failed to merge policy data objects"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/policy-data/latest": {
"get": {
"tags": [
"policy-data"
],
"summary": "Get the latest policy data",
"operationId": "getLatestPolicyData",
"responses": {
"200": {
"description": "Latest policy data was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_PolicyData"
},
"example": {
"data": {
"type": "policy-data",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"data": {
"hello": "world",
"foo": 42,
"bar": true
}
},
"links": {
"self": "/api/admin/v1/policy-data/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/policy-data/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "No policy data was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "No policy data found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/policy-data/{id}": {
"get": {
"tags": [
"policy-data"
],
"summary": "Get policy data by ID",
"operationId": "getPolicyData",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "Policy data was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_PolicyData"
},
"example": {
"data": {
"type": "policy-data",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"data": {
"hello": "world",
"foo": 42,
"bar": true
}
},
"links": {
"self": "/api/admin/v1/policy-data/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/policy-data/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "Policy data was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Policy data with ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users": {
"get": {
"tags": [
"user"
],
"summary": "List users",
"operationId": "listUsers",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "count",
"description": "Include the total number of items. Defaults to `true`.",
"schema": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[admin]",
"description": "Retrieve users with (or without) the `admin` flag set",
"schema": {
"description": "Retrieve users with (or without) the `admin` flag set",
"type": [
"boolean",
"null"
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[legacy-guest]",
"description": "Retrieve users with (or without) the `legacy_guest` flag set",
"schema": {
"description": "Retrieve users with (or without) the `legacy_guest` flag set",
"type": [
"boolean",
"null"
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[search]",
"description": "Retrieve users where the username matches contains the given string\n\n Note that this doesn't change the ordering of the result, which are\n still ordered by ID.",
"schema": {
"description": "Retrieve users where the username matches contains the given string\n\n Note that this doesn't change the ordering of the result, which are\n still ordered by ID.",
"type": [
"string",
"null"
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[status]",
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all users, including locked ones.\n\n * `active`: Only retrieve active users\n\n * `locked`: Only retrieve locked users (includes deactivated users)\n\n * `deactivated`: Only retrieve deactivated users",
"schema": {
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all users, including locked ones.\n\n * `active`: Only retrieve active users\n\n * `locked`: Only retrieve locked users (includes deactivated users)\n\n * `deactivated`: Only retrieve deactivated users",
"anyOf": [
{
"$ref": "#/components/schemas/UserStatus"
},
{
"type": "null"
}
]
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of users",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_User"
},
"example": {
"meta": {
"count": 42
},
"data": [
{
"type": "user",
"id": "01040G2081040G2081040G2081",
"attributes": {
"username": "alice",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": null,
"deactivated_at": null,
"admin": false,
"legacy_guest": false
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
},
"meta": {
"page": {
"cursor": "01040G2081040G2081040G2081"
}
}
},
{
"type": "user",
"id": "02081040G2081040G2081040G2",
"attributes": {
"username": "bob",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": null,
"deactivated_at": null,
"admin": true,
"legacy_guest": false
},
"links": {
"self": "/api/admin/v1/users/02081040G2081040G2081040G2"
},
"meta": {
"page": {
"cursor": "02081040G2081040G2081040G2"
}
}
},
{
"type": "user",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"username": "charlie",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": "1970-01-01T00:00:00Z",
"deactivated_at": null,
"admin": false,
"legacy_guest": true
},
"links": {
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3"
},
"meta": {
"page": {
"cursor": "030C1G60R30C1G60R30C1G60R3"
}
}
}
],
"links": {
"self": "/api/admin/v1/users?page[first]=3",
"first": "/api/admin/v1/users?page[first]=3",
"last": "/api/admin/v1/users?page[last]=3",
"next": "/api/admin/v1/users?page[after]=030C1G60R30C1G60R30C1G60R3&page[first]=3"
}
}
}
}
}
}
},
"post": {
"tags": [
"user"
],
"summary": "Create a new user",
"operationId": "createUser",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddUserRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "User was created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "01040G2081040G2081040G2081",
"attributes": {
"username": "alice",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": null,
"deactivated_at": null,
"admin": false,
"legacy_guest": false
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
}
}
}
},
"400": {
"description": "Username is not valid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Username is not valid"
}
]
}
}
}
},
"409": {
"description": "Username is reserved by the homeserver",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Username is reserved by the homeserver"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}": {
"get": {
"tags": [
"user"
],
"summary": "Get a user",
"operationId": "getUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "01040G2081040G2081040G2081",
"attributes": {
"username": "alice",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": null,
"deactivated_at": null,
"admin": false,
"legacy_guest": false
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/set-password": {
"post": {
"tags": [
"user"
],
"summary": "Set the password for a user",
"operationId": "setUserPassword",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetUserPasswordRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Password was set"
},
"400": {
"description": "Password is too weak",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Password is too weak"
}
]
}
}
}
},
"403": {
"description": "Password auth is disabled in the server configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Password auth is disabled"
}
]
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/by-username/{username}": {
"get": {
"tags": [
"user"
],
"summary": "Get a user by its username (localpart)",
"operationId": "getUserByUsername",
"parameters": [
{
"in": "path",
"name": "username",
"description": "The username (localpart) of the user to get",
"required": true,
"schema": {
"description": "The username (localpart) of the user to get",
"type": "string"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "01040G2081040G2081040G2081",
"attributes": {
"username": "alice",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": null,
"deactivated_at": null,
"admin": false,
"legacy_guest": false
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/users/by-username/alice"
}
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User with username \"alice\" not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/set-admin": {
"post": {
"tags": [
"user"
],
"summary": "Set whether a user can request admin",
"description": "Calling this endpoint will not have any effect on existing sessions, meaning that their existing sessions will keep admin access if they were granted it.",
"operationId": "userSetAdmin",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserSetAdminRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "User had admin privileges set",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "02081040G2081040G2081040G2",
"attributes": {
"username": "bob",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": null,
"deactivated_at": null,
"admin": true,
"legacy_guest": false
},
"links": {
"self": "/api/admin/v1/users/02081040G2081040G2081040G2"
}
},
"links": {
"self": "/api/admin/v1/users/02081040G2081040G2081040G2/set-admin"
}
}
}
}
},
"404": {
"description": "User ID not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/deactivate": {
"post": {
"tags": [
"user"
],
"summary": "Deactivate a user",
"description": "Calling this endpoint will deactivate the user, preventing them from doing any action.\nThis invalidates any existing session, and will ask the homeserver to make them leave all rooms.",
"operationId": "deactivateUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeactivateUserRequest"
}
}
}
},
"responses": {
"200": {
"description": "User was deactivated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"username": "charlie",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": "1970-01-01T00:00:00Z",
"deactivated_at": null,
"admin": false,
"legacy_guest": true
},
"links": {
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3"
}
},
"links": {
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3/deactivate"
}
}
}
}
},
"404": {
"description": "User ID not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/reactivate": {
"post": {
"tags": [
"user"
],
"summary": "Reactivate a user",
"description": "Calling this endpoint will reactivate a deactivated user.\nThis DOES NOT unlock a locked user, which is still prevented from doing any action until it is explicitly unlocked.",
"operationId": "reactivateUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User was reactivated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "01040G2081040G2081040G2081",
"attributes": {
"username": "alice",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": null,
"deactivated_at": null,
"admin": false,
"legacy_guest": false
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081/reactivate"
}
}
}
}
},
"404": {
"description": "User ID not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/lock": {
"post": {
"tags": [
"user"
],
"summary": "Lock a user",
"description": "Calling this endpoint will lock the user, preventing them from doing any action.\nThis DOES NOT invalidate any existing session, meaning that all their existing sessions will work again as soon as they get unlocked.",
"operationId": "lockUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User was locked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"username": "charlie",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": "1970-01-01T00:00:00Z",
"deactivated_at": null,
"admin": false,
"legacy_guest": true
},
"links": {
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3"
}
},
"links": {
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3/lock"
}
}
}
}
},
"404": {
"description": "User ID not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/unlock": {
"post": {
"tags": [
"user"
],
"summary": "Unlock a user",
"description": "Calling this endpoint will lift restrictions on user actions that had imposed by locking.\nThis DOES NOT reactivate a deactivated user, which will remain unavailable until it is explicitly reactivated.",
"operationId": "unlockUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User was unlocked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "01040G2081040G2081040G2081",
"attributes": {
"username": "alice",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": null,
"deactivated_at": null,
"admin": false,
"legacy_guest": false
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081/unlock"
}
}
}
}
},
"404": {
"description": "User ID not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/user-emails": {
"get": {
"tags": [
"user-email"
],
"summary": "List user emails",
"description": "Retrieve a list of user emails.",
"operationId": "listUserEmails",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "count",
"description": "Include the total number of items. Defaults to `true`.",
"schema": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[user]",
"description": "Retrieve the items for the given user",
"schema": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[email]",
"description": "Retrieve the user email with the given email address",
"schema": {
"description": "Retrieve the user email with the given email address",
"type": [
"string",
"null"
]
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of user emails",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_UserEmail"
},
"example": {
"meta": {
"count": 42
},
"data": [
{
"type": "user-email",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"user_id": "02081040G2081040G2081040G2",
"email": "alice@example.com"
},
"links": {
"self": "/api/admin/v1/user-emails/01040G2081040G2081040G2081"
},
"meta": {
"page": {
"cursor": "01040G2081040G2081040G2081"
}
}
}
],
"links": {
"self": "/api/admin/v1/user-emails?page[first]=1",
"first": "/api/admin/v1/user-emails?page[first]=1",
"last": "/api/admin/v1/user-emails?page[last]=1",
"next": "/api/admin/v1/user-emails?page[after]=01040G2081040G2081040G2081&page[first]=1"
}
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
},
"post": {
"tags": [
"user-email"
],
"summary": "Add a user email",
"description": "Add an email address to a user.\nNote that this endpoint ignores any policy which would normally prevent the email from being added.",
"operationId": "addUserEmail",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddUserEmailRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "User email was created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UserEmail"
},
"example": {
"data": {
"type": "user-email",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"user_id": "02081040G2081040G2081040G2",
"email": "alice@example.com"
},
"links": {
"self": "/api/admin/v1/user-emails/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/user-emails/01040G2081040G2081040G2081"
}
}
}
}
},
"409": {
"description": "Email already in use",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User email \"alice@example.com\" already in use"
}
]
}
}
}
},
"400": {
"description": "Email is not valid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Email \"not a valid email\" is not valid"
},
{
"title": "Missing domain or user"
}
]
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/user-emails/{id}": {
"get": {
"tags": [
"user-email"
],
"summary": "Get a user email",
"operationId": "getUserEmail",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User email was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UserEmail"
},
"example": {
"data": {
"type": "user-email",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"user_id": "02081040G2081040G2081040G2",
"email": "alice@example.com"
},
"links": {
"self": "/api/admin/v1/user-emails/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/user-emails/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "User email was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User email ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"user-email"
],
"summary": "Delete a user email",
"operationId": "deleteUserEmail",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"204": {
"description": "User email was found"
},
"404": {
"description": "User email was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User email ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/user-sessions": {
"get": {
"tags": [
"user-session"
],
"summary": "List user sessions",
"description": "Retrieve a list of user sessions (browser sessions).\nNote that by default, all sessions, including finished ones are returned, with the oldest first.\nUse the `filter[status]` parameter to filter the sessions by their status and `page[last]` parameter to retrieve the last N sessions.",
"operationId": "listUserSessions",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "count",
"description": "Include the total number of items. Defaults to `true`.",
"schema": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[user]",
"description": "Retrieve the items for the given user",
"schema": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[status]",
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all sessions, including finished ones.\n\n * `active`: Only retrieve active sessions\n\n * `finished`: Only retrieve finished sessions",
"schema": {
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all sessions, including finished ones.\n\n * `active`: Only retrieve active sessions\n\n * `finished`: Only retrieve finished sessions",
"anyOf": [
{
"$ref": "#/components/schemas/UserSessionStatus"
},
{
"type": "null"
}
]
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of user sessions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_UserSession"
},
"example": {
"meta": {
"count": 42
},
"data": [
{
"type": "user-session",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": null,
"user_id": "02081040G2081040G2081040G2",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1"
},
"links": {
"self": "/api/admin/v1/user-sessions/01040G2081040G2081040G2081"
},
"meta": {
"page": {
"cursor": "01040G2081040G2081040G2081"
}
}
},
{
"type": "user-session",
"id": "02081040G2081040G2081040G2",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": null,
"user_id": "030C1G60R30C1G60R30C1G60R3",
"user_agent": null,
"last_active_at": null,
"last_active_ip": null
},
"links": {
"self": "/api/admin/v1/user-sessions/02081040G2081040G2081040G2"
},
"meta": {
"page": {
"cursor": "02081040G2081040G2081040G2"
}
}
},
{
"type": "user-session",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": "1970-01-01T00:00:00Z",
"user_id": "040G2081040G2081040G208104",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1"
},
"links": {
"self": "/api/admin/v1/user-sessions/030C1G60R30C1G60R30C1G60R3"
},
"meta": {
"page": {
"cursor": "030C1G60R30C1G60R30C1G60R3"
}
}
}
],
"links": {
"self": "/api/admin/v1/user-sessions?page[first]=3",
"first": "/api/admin/v1/user-sessions?page[first]=3",
"last": "/api/admin/v1/user-sessions?page[last]=3",
"next": "/api/admin/v1/user-sessions?page[after]=030C1G60R30C1G60R30C1G60R3&page[first]=3"
}
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/user-sessions/{id}": {
"get": {
"tags": [
"user-session"
],
"summary": "Get a user session",
"operationId": "getUserSession",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User session was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UserSession"
},
"example": {
"data": {
"type": "user-session",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": null,
"user_id": "02081040G2081040G2081040G2",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1"
},
"links": {
"self": "/api/admin/v1/user-sessions/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/user-sessions/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "User session was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User session ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/user-sessions/{id}/finish": {
"post": {
"tags": [
"user-session"
],
"summary": "Finish a user session",
"description": "Calling this endpoint will finish the user session, preventing any further use.",
"operationId": "finishUserSession",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User session was finished",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UserSession"
},
"example": {
"data": {
"type": "user-session",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": "1970-01-01T00:00:00Z",
"user_id": "040G2081040G2081040G208104",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1"
},
"links": {
"self": "/api/admin/v1/user-sessions/030C1G60R30C1G60R30C1G60R3"
}
},
"links": {
"self": "/api/admin/v1/user-sessions/030C1G60R30C1G60R30C1G60R3/finish"
}
}
}
}
},
"400": {
"description": "Session is already finished",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User session with ID 00000000000000000000000000 is already finished"
}
]
}
}
}
},
"404": {
"description": "User session was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User session with ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/user-registration-tokens": {
"get": {
"tags": [
"user-registration-token"
],
"summary": "List user registration tokens",
"operationId": "listUserRegistrationTokens",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "count",
"description": "Include the total number of items. Defaults to `true`.",
"schema": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[used]",
"description": "Retrieve tokens that have (or have not) been used at least once",
"schema": {
"description": "Retrieve tokens that have (or have not) been used at least once",
"type": [
"boolean",
"null"
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[revoked]",
"description": "Retrieve tokens that are (or are not) revoked",
"schema": {
"description": "Retrieve tokens that are (or are not) revoked",
"type": [
"boolean",
"null"
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[expired]",
"description": "Retrieve tokens that are (or are not) expired",
"schema": {
"description": "Retrieve tokens that are (or are not) expired",
"type": [
"boolean",
"null"
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[valid]",
"description": "Retrieve tokens that are (or are not) valid\n\n Valid means that the token has not expired, is not revoked, and has not\n reached its usage limit.",
"schema": {
"description": "Retrieve tokens that are (or are not) valid\n\n Valid means that the token has not expired, is not revoked, and has not\n reached its usage limit.",
"type": [
"boolean",
"null"
]
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of registration tokens",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_UserRegistrationToken"
},
"example": {
"meta": {
"count": 42
},
"data": [
{
"type": "user-registration_token",
"id": "01040G2081040G2081040G2081",
"attributes": {
"token": "abc123def456",
"valid": true,
"usage_limit": 10,
"times_used": 5,
"created_at": "1970-01-01T00:00:00Z",
"last_used_at": "1970-01-01T00:00:00Z",
"expires_at": "1970-01-31T00:00:00Z",
"revoked_at": null
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/01040G2081040G2081040G2081"
},
"meta": {
"page": {
"cursor": "01040G2081040G2081040G2081"
}
}
},
{
"type": "user-registration_token",
"id": "02081040G2081040G2081040G2",
"attributes": {
"token": "xyz789abc012",
"valid": false,
"usage_limit": null,
"times_used": 0,
"created_at": "1970-01-01T00:00:00Z",
"last_used_at": null,
"expires_at": null,
"revoked_at": "1970-01-01T00:00:00Z"
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/02081040G2081040G2081040G2"
},
"meta": {
"page": {
"cursor": "02081040G2081040G2081040G2"
}
}
}
],
"links": {
"self": "/api/admin/v1/user-registration-tokens?page[first]=2",
"first": "/api/admin/v1/user-registration-tokens?page[first]=2",
"last": "/api/admin/v1/user-registration-tokens?page[last]=2",
"next": "/api/admin/v1/user-registration-tokens?page[after]=02081040G2081040G2081040G2&page[first]=2"
}
}
}
}
}
}
},
"post": {
"tags": [
"user-registration-token"
],
"summary": "Create a new user registration token",
"operationId": "addUserRegistrationToken",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddUserRegistrationTokenRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "A new user registration token was created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UserRegistrationToken"
},
"example": {
"data": {
"type": "user-registration_token",
"id": "01040G2081040G2081040G2081",
"attributes": {
"token": "abc123def456",
"valid": true,
"usage_limit": 10,
"times_used": 5,
"created_at": "1970-01-01T00:00:00Z",
"last_used_at": "1970-01-01T00:00:00Z",
"expires_at": "1970-01-31T00:00:00Z",
"revoked_at": null
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/01040G2081040G2081040G2081"
}
}
}
}
}
}
}
},
"/api/admin/v1/user-registration-tokens/{id}": {
"get": {
"tags": [
"user-registration-token"
],
"summary": "Get a user registration token",
"operationId": "getUserRegistrationToken",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "Registration token was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UserRegistrationToken"
},
"example": {
"data": {
"type": "user-registration_token",
"id": "01040G2081040G2081040G2081",
"attributes": {
"token": "abc123def456",
"valid": true,
"usage_limit": 10,
"times_used": 5,
"created_at": "1970-01-01T00:00:00Z",
"last_used_at": "1970-01-01T00:00:00Z",
"expires_at": "1970-01-31T00:00:00Z",
"revoked_at": null
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "Registration token was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Registration token with ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
},
"put": {
"tags": [
"user-registration-token"
],
"summary": "Update a user registration token",
"description": "Update properties of a user registration token such as expiration and usage limit. To set a field to null (removing the limit/expiration), include the field with a null value. To leave a field unchanged, omit it from the request body.",
"operationId": "updateUserRegistrationToken",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditUserRegistrationTokenRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Registration token was updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UserRegistrationToken"
},
"example": {
"data": {
"type": "user-registration_token",
"id": "01040G2081040G2081040G2081",
"attributes": {
"token": "abc123def456",
"valid": true,
"usage_limit": 10,
"times_used": 5,
"created_at": "1970-01-01T00:00:00Z",
"last_used_at": "1970-01-01T00:00:00Z",
"expires_at": "1970-01-31T00:00:00Z",
"revoked_at": null
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "Registration token was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Registration token with ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/user-registration-tokens/{id}/revoke": {
"post": {
"tags": [
"user-registration-token"
],
"summary": "Revoke a user registration token",
"description": "Calling this endpoint will revoke the user registration token, preventing it from being used for new registrations.",
"operationId": "revokeUserRegistrationToken",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "Registration token was revoked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UserRegistrationToken"
},
"example": {
"data": {
"type": "user-registration_token",
"id": "02081040G2081040G2081040G2",
"attributes": {
"token": "xyz789abc012",
"valid": false,
"usage_limit": null,
"times_used": 0,
"created_at": "1970-01-01T00:00:00Z",
"last_used_at": null,
"expires_at": null,
"revoked_at": "1970-01-01T00:00:00Z"
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/02081040G2081040G2081040G2"
}
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/02081040G2081040G2081040G2/revoke"
}
}
}
}
},
"400": {
"description": "Token is already revoked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Registration token with ID 00000000000000000000000000 is already revoked"
}
]
}
}
}
},
"404": {
"description": "Registration token was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Registration token with ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/user-registration-tokens/{id}/unrevoke": {
"post": {
"tags": [
"user-registration-token"
],
"summary": "Unrevoke a user registration token",
"description": "Calling this endpoint will unrevoke a previously revoked user registration token, allowing it to be used for registrations again (subject to its usage limits and expiration).",
"operationId": "unrevokeUserRegistrationToken",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "Registration token was unrevoked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UserRegistrationToken"
},
"example": {
"data": {
"type": "user-registration_token",
"id": "01040G2081040G2081040G2081",
"attributes": {
"token": "abc123def456",
"valid": true,
"usage_limit": 10,
"times_used": 5,
"created_at": "1970-01-01T00:00:00Z",
"last_used_at": "1970-01-01T00:00:00Z",
"expires_at": "1970-01-31T00:00:00Z",
"revoked_at": null
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/user-registration-tokens/01040G2081040G2081040G2081/unrevoke"
}
}
}
}
},
"400": {
"description": "Token is not revoked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Registration token with ID 00000000000000000000000000 is not revoked"
}
]
}
}
}
},
"404": {
"description": "Registration token was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Registration token with ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/upstream-oauth-links": {
"get": {
"tags": [
"upstream-oauth-link"
],
"summary": "List upstream OAuth 2.0 links",
"description": "Retrieve a list of upstream OAuth 2.0 links.",
"operationId": "listUpstreamOAuthLinks",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "count",
"description": "Include the total number of items. Defaults to `true`.",
"schema": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[user]",
"description": "Retrieve the items for the given user",
"schema": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[provider]",
"description": "Retrieve the items for the given provider",
"schema": {
"description": "Retrieve the items for the given provider",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[subject]",
"description": "Retrieve the items with the given subject",
"schema": {
"description": "Retrieve the items with the given subject",
"type": [
"string",
"null"
]
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of upstream OAuth 2.0 links",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_UpstreamOAuthLink"
},
"example": {
"meta": {
"count": 42
},
"data": [
{
"type": "upstream-oauth-link",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"provider_id": "02081040G2081040G2081040G2",
"subject": "john-42",
"user_id": "030C1G60R30C1G60R30C1G60R3",
"human_account_name": "john.doe@example.com"
},
"links": {
"self": "/api/admin/v1/upstream-oauth-links/01040G2081040G2081040G2081"
},
"meta": {
"page": {
"cursor": "01040G2081040G2081040G2081"
}
}
},
{
"type": "upstream-oauth-link",
"id": "02081040G2081040G2081040G2",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"provider_id": "030C1G60R30C1G60R30C1G60R3",
"subject": "jane-123",
"user_id": null,
"human_account_name": null
},
"links": {
"self": "/api/admin/v1/upstream-oauth-links/02081040G2081040G2081040G2"
},
"meta": {
"page": {
"cursor": "02081040G2081040G2081040G2"
}
}
},
{
"type": "upstream-oauth-link",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"provider_id": "040G2081040G2081040G208104",
"subject": "bob@social.example.com",
"user_id": "050M2GA1850M2GA1850M2GA185",
"human_account_name": "bob"
},
"links": {
"self": "/api/admin/v1/upstream-oauth-links/030C1G60R30C1G60R30C1G60R3"
},
"meta": {
"page": {
"cursor": "030C1G60R30C1G60R30C1G60R3"
}
}
}
],
"links": {
"self": "/api/admin/v1/upstream-oauth-links?page[first]=3",
"first": "/api/admin/v1/upstream-oauth-links?page[first]=3",
"last": "/api/admin/v1/upstream-oauth-links?page[last]=3",
"next": "/api/admin/v1/upstream-oauth-links?page[after]=030C1G60R30C1G60R30C1G60R3&page[first]=3"
}
}
}
}
},
"404": {
"description": "User or provider was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
},
"post": {
"tags": [
"upstream-oauth-link"
],
"summary": "Add an upstream OAuth 2.0 link",
"operationId": "addUpstreamOAuthLink",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddUpstreamOauthLinkRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "An existing Upstream OAuth 2.0 link was associated to a user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UpstreamOAuthLink"
},
"example": {
"data": {
"type": "upstream-oauth-link",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"provider_id": "02081040G2081040G2081040G2",
"subject": "john-42",
"user_id": "030C1G60R30C1G60R30C1G60R3",
"human_account_name": "john.doe@example.com"
},
"links": {
"self": "/api/admin/v1/upstream-oauth-links/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/upstream-oauth-links/01040G2081040G2081040G2081"
}
}
}
}
},
"201": {
"description": "A new Upstream OAuth 2.0 link was created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UpstreamOAuthLink"
},
"example": {
"data": {
"type": "upstream-oauth-link",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"provider_id": "02081040G2081040G2081040G2",
"subject": "john-42",
"user_id": "030C1G60R30C1G60R30C1G60R3",
"human_account_name": "john.doe@example.com"
},
"links": {
"self": "/api/admin/v1/upstream-oauth-links/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/upstream-oauth-links/01040G2081040G2081040G2081"
}
}
}
}
},
"409": {
"description": "The subject from the provider is already linked to another user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Upstream Oauth 2.0 Provider ID 01040G2081040G2081040G2081 with subject subject1 is already linked to a user"
}
]
}
}
}
},
"404": {
"description": "User or provider was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/upstream-oauth-links/{id}": {
"get": {
"tags": [
"upstream-oauth-link"
],
"summary": "Get an upstream OAuth 2.0 link",
"operationId": "getUpstreamOAuthLink",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "Upstream OAuth 2.0 link was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UpstreamOAuthLink"
},
"example": {
"data": {
"type": "upstream-oauth-link",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"provider_id": "02081040G2081040G2081040G2",
"subject": "john-42",
"user_id": "030C1G60R30C1G60R30C1G60R3",
"human_account_name": "john.doe@example.com"
},
"links": {
"self": "/api/admin/v1/upstream-oauth-links/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/upstream-oauth-links/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "Upstream OAuth 2.0 link was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Upstream OAuth 2.0 Link ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"upstream-oauth-link"
],
"summary": "Delete an upstream OAuth 2.0 link",
"operationId": "deleteUpstreamOAuthLink",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"204": {
"description": "Upstream OAuth 2.0 link was deleted"
},
"404": {
"description": "Upstream OAuth 2.0 link was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Upstream OAuth 2.0 Link ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/upstream-oauth-providers": {
"get": {
"tags": [
"upstream-oauth-provider"
],
"summary": "List upstream OAuth 2.0 providers",
"operationId": "listUpstreamOAuthProviders",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"style": "form"
},
{
"in": "query",
"name": "count",
"description": "Include the total number of items. Defaults to `true`.",
"schema": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
},
"style": "form"
},
{
"in": "query",
"name": "filter[enabled]",
"description": "Retrieve providers that are (or are not) enabled",
"schema": {
"description": "Retrieve providers that are (or are not) enabled",
"type": [
"boolean",
"null"
]
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of upstream OAuth 2.0 providers",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_UpstreamOAuthProvider"
},
"example": {
"meta": {
"count": 42
},
"data": [
{
"type": "upstream-oauth-provider",
"id": "01040G2081040G2081040G2081",
"attributes": {
"issuer": "https://accounts.google.com",
"human_name": "Google",
"brand_name": "google",
"created_at": "1970-01-01T00:00:00Z",
"disabled_at": null
},
"links": {
"self": "/api/admin/v1/upstream-oauth-providers/01040G2081040G2081040G2081"
},
"meta": {
"page": {
"cursor": "01040G2081040G2081040G2081"
}
}
},
{
"type": "upstream-oauth-provider",
"id": "02081040G2081040G2081040G2",
"attributes": {
"issuer": "https://appleid.apple.com",
"human_name": "Apple ID",
"brand_name": "apple",
"created_at": "1970-01-01T00:00:00Z",
"disabled_at": "1970-01-01T00:00:00Z"
},
"links": {
"self": "/api/admin/v1/upstream-oauth-providers/02081040G2081040G2081040G2"
},
"meta": {
"page": {
"cursor": "02081040G2081040G2081040G2"
}
}
},
{
"type": "upstream-oauth-provider",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"issuer": null,
"human_name": "Custom OAuth Provider",
"brand_name": null,
"created_at": "1970-01-01T00:00:00Z",
"disabled_at": null
},
"links": {
"self": "/api/admin/v1/upstream-oauth-providers/030C1G60R30C1G60R30C1G60R3"
},
"meta": {
"page": {
"cursor": "030C1G60R30C1G60R30C1G60R3"
}
}
}
],
"links": {
"self": "/api/admin/v1/upstream-oauth-providers?page[first]=3",
"first": "/api/admin/v1/upstream-oauth-providers?page[first]=3",
"last": "/api/admin/v1/upstream-oauth-providers?page[last]=3",
"next": "/api/admin/v1/upstream-oauth-providers?page[after]=030C1G60R30C1G60R30C1G60R3&page[first]=3"
}
}
}
}
}
}
}
},
"/api/admin/v1/upstream-oauth-providers/{id}": {
"get": {
"tags": [
"upstream-oauth-provider"
],
"summary": "Get upstream OAuth provider",
"operationId": "getUpstreamOAuthProvider",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "The upstream OAuth provider",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_UpstreamOAuthProvider"
},
"example": {
"data": {
"type": "upstream-oauth-provider",
"id": "01040G2081040G2081040G2081",
"attributes": {
"issuer": "https://accounts.google.com",
"human_name": "Google",
"brand_name": "google",
"created_at": "1970-01-01T00:00:00Z",
"disabled_at": null
},
"links": {
"self": "/api/admin/v1/upstream-oauth-providers/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/upstream-oauth-providers/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "Provider not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"oauth2": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"refreshUrl": "./oauth2/token",
"tokenUrl": "./oauth2/token",
"scopes": {
"urn:mas:admin": "Grant access to the admin API"
}
},
"authorizationCode": {
"authorizationUrl": "./authorize",
"tokenUrl": "./oauth2/token",
"refreshUrl": "./oauth2/token",
"scopes": {
"urn:mas:admin": "Grant access to the admin API"
}
}
}
},
"token": {
"type": "http",
"scheme": "bearer",
"description": "An access token with access to the admin API"
}
},
"schemas": {
"SiteConfig": {
"type": "object",
"properties": {
"server_name": {
"description": "The Matrix server name for which this instance is configured",
"type": "string"
},
"password_login_enabled": {
"description": "Whether password login is enabled.",
"type": "boolean"
},
"password_registration_enabled": {
"description": "Whether password registration is enabled.",
"type": "boolean"
},
"password_registration_email_required": {
"description": "Whether a valid email address is required for password registrations.",
"type": "boolean"
},
"registration_token_required": {
"description": "Whether registration tokens are required for password registrations.",
"type": "boolean"
},
"email_change_allowed": {
"description": "Whether users can change their email.",
"type": "boolean"
},
"displayname_change_allowed": {
"description": "Whether users can change their display name.",
"type": "boolean"
},
"password_change_allowed": {
"description": "Whether users can change their password.",
"type": "boolean"
},
"account_recovery_allowed": {
"description": "Whether users can recover their account via email.",
"type": "boolean"
},
"account_deactivation_allowed": {
"description": "Whether users can delete their own account.",
"type": "boolean"
},
"captcha_enabled": {
"description": "Whether CAPTCHA during registration is enabled.",
"type": "boolean"
},
"minimum_password_complexity": {
"description": "Minimum password complexity, between 0 and 4.\n This is a score from zxcvbn.",
"type": "integer",
"format": "uint8",
"minimum": 0,
"maximum": 4
}
},
"required": [
"server_name",
"password_login_enabled",
"password_registration_enabled",
"password_registration_email_required",
"registration_token_required",
"email_change_allowed",
"displayname_change_allowed",
"password_change_allowed",
"account_recovery_allowed",
"account_deactivation_allowed",
"captcha_enabled",
"minimum_password_complexity"
]
},
"Version": {
"type": "object",
"properties": {
"version": {
"description": "The semver version of the app",
"type": "string"
}
},
"required": [
"version"
]
},
"PaginationParams": {
"type": "object",
"properties": {
"page[before]": {
"description": "Retrieve the items before the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"page[after]": {
"description": "Retrieve the items after the given ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"page[first]": {
"description": "Retrieve the first N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"page[last]": {
"description": "Retrieve the last N items",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 1
},
"count": {
"description": "Include the total number of items. Defaults to `true`.",
"anyOf": [
{
"$ref": "#/components/schemas/IncludeCount"
},
{
"type": "null"
}
]
}
}
},
"ULID": {
"title": "ULID",
"description": "A ULID as per https://github.com/ulid/spec",
"type": "string",
"pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$",
"example": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
},
"IncludeCount": {
"oneOf": [
{
"description": "Include the total number of items (default)",
"type": "string",
"enum": [
"true"
]
},
{
"description": "Do not include the total number of items",
"type": "string",
"enum": [
"false"
]
},
{
"description": "Only include the total number of items, skip the items themselves",
"type": "string",
"enum": [
"only"
]
}
]
},
"CompatSessionFilter": {
"type": "object",
"properties": {
"filter[user]": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[user-session]": {
"description": "Retrieve the items started from the given browser session",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[status]": {
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all sessions, including finished ones.\n\n * `active`: Only retrieve active sessions\n\n * `finished`: Only retrieve finished sessions",
"anyOf": [
{
"$ref": "#/components/schemas/CompatSessionStatus"
},
{
"type": "null"
}
]
}
}
},
"CompatSessionStatus": {
"type": "string",
"enum": [
"active",
"finished"
]
},
"PaginatedResponse_for_CompatSession": {
"description": "A top-level response with a page of resources",
"type": "object",
"properties": {
"meta": {
"description": "Response metadata",
"anyOf": [
{
"$ref": "#/components/schemas/PaginationMeta"
},
{
"type": "null"
}
]
},
"data": {
"description": "The list of resources",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SingleResource_for_CompatSession"
}
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/PaginationLinks"
}
]
}
},
"required": [
"links"
]
},
"PaginationMeta": {
"type": "object",
"properties": {
"count": {
"description": "The total number of results",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 0
}
}
},
"SingleResource_for_CompatSession": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/CompatSession"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"CompatSession": {
"description": "A compatibility session for legacy clients",
"type": "object",
"properties": {
"user_id": {
"description": "The ID of the user that owns this session",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"device_id": {
"description": "The Matrix device ID of this session",
"allOf": [
{
"$ref": "#/components/schemas/DeviceID"
}
]
},
"user_session_id": {
"description": "The ID of the user session that started this session, if any",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"redirect_uri": {
"description": "The redirect URI used to login in the client, if it was an SSO login",
"type": [
"string",
"null"
],
"format": "uri"
},
"created_at": {
"description": "The time this session was created",
"type": "string",
"format": "date-time"
},
"user_agent": {
"description": "The user agent string that started this session, if any",
"type": [
"string",
"null"
]
},
"last_active_at": {
"description": "The time this session was last active",
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_active_ip": {
"description": "The last IP address recorded for this session",
"type": [
"string",
"null"
],
"format": "ip"
},
"finished_at": {
"description": "The time this session was finished",
"type": [
"string",
"null"
],
"format": "date-time"
},
"human_name": {
"description": "The user-provided name, if any",
"type": [
"string",
"null"
]
}
},
"required": [
"user_id",
"device_id",
"user_session_id",
"created_at"
]
},
"DeviceID": {
"title": "Device ID",
"description": "A device ID as per https://matrix.org/docs/spec/client_server/r0.6.0#device-ids",
"type": "string",
"pattern": "^[A-Za-z0-9._~!$&'()*+,;=:&/-]+$",
"example": "AABBCCDDEE"
},
"SelfLinks": {
"description": "Related links",
"type": "object",
"properties": {
"self": {
"description": "The canonical link to the current resource",
"type": "string"
}
},
"required": [
"self"
]
},
"SingleResourceMeta": {
"description": "Metadata associated with a resource",
"type": "object",
"properties": {
"page": {
"description": "Information about the pagination of the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMetaPage"
},
{
"type": "null"
}
]
}
}
},
"SingleResourceMetaPage": {
"description": "Pagination metadata for a resource",
"type": "object",
"properties": {
"cursor": {
"description": "The cursor of this resource in the paginated result",
"type": "string"
}
},
"required": [
"cursor"
]
},
"PaginationLinks": {
"description": "Related links",
"type": "object",
"properties": {
"self": {
"description": "The canonical link to the current page",
"type": "string"
},
"first": {
"description": "The link to the first page of results",
"type": [
"string",
"null"
]
},
"last": {
"description": "The link to the last page of results",
"type": [
"string",
"null"
]
},
"next": {
"description": "The link to the next page of results\n\n Only present if there is a next page",
"type": [
"string",
"null"
]
},
"prev": {
"description": "The link to the previous page of results\n\n Only present if there is a previous page",
"type": [
"string",
"null"
]
}
},
"required": [
"self"
]
},
"ErrorResponse": {
"description": "A top-level response with a list of errors",
"type": "object",
"properties": {
"errors": {
"description": "The list of errors",
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
}
},
"required": [
"errors"
]
},
"Error": {
"description": "A single error",
"type": "object",
"properties": {
"title": {
"description": "A human-readable title for the error",
"type": "string"
}
},
"required": [
"title"
]
},
"UlidInPath": {
"type": "object",
"properties": {
"id": {
"title": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
}
},
"required": [
"id"
]
},
"SingleResponse_for_CompatSession": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_CompatSession"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
},
"OAuth2SessionFilter": {
"type": "object",
"properties": {
"filter[user]": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[client]": {
"description": "Retrieve the items for the given client",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[client-kind]": {
"description": "Retrieve the items only for a specific client kind",
"anyOf": [
{
"$ref": "#/components/schemas/OAuth2ClientKind"
},
{
"type": "null"
}
]
},
"filter[user-session]": {
"description": "Retrieve the items started from the given browser session",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[scope]": {
"description": "Retrieve the items with the given scope",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"filter[status]": {
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all sessions, including finished ones.\n\n * `active`: Only retrieve active sessions\n\n * `finished`: Only retrieve finished sessions",
"anyOf": [
{
"$ref": "#/components/schemas/OAuth2SessionStatus"
},
{
"type": "null"
}
]
}
}
},
"OAuth2ClientKind": {
"type": "string",
"enum": [
"dynamic",
"static"
]
},
"OAuth2SessionStatus": {
"type": "string",
"enum": [
"active",
"finished"
]
},
"PaginatedResponse_for_OAuth2Session": {
"description": "A top-level response with a page of resources",
"type": "object",
"properties": {
"meta": {
"description": "Response metadata",
"anyOf": [
{
"$ref": "#/components/schemas/PaginationMeta"
},
{
"type": "null"
}
]
},
"data": {
"description": "The list of resources",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SingleResource_for_OAuth2Session"
}
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/PaginationLinks"
}
]
}
},
"required": [
"links"
]
},
"SingleResource_for_OAuth2Session": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/OAuth2Session"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"OAuth2Session": {
"description": "A OAuth 2.0 session",
"type": "object",
"properties": {
"created_at": {
"description": "When the object was created",
"type": "string",
"format": "date-time"
},
"finished_at": {
"description": "When the session was finished",
"type": [
"string",
"null"
],
"format": "date-time"
},
"user_id": {
"description": "The ID of the user who owns the session",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"user_session_id": {
"description": "The ID of the browser session which started this session",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"client_id": {
"description": "The ID of the client which requested this session",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"scope": {
"description": "The scope granted for this session",
"type": "string"
},
"user_agent": {
"description": "The user agent string of the client which started this session",
"type": [
"string",
"null"
]
},
"last_active_at": {
"description": "The last time the session was active",
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_active_ip": {
"description": "The last IP address used by the session",
"type": [
"string",
"null"
],
"format": "ip"
},
"human_name": {
"description": "The user-provided name, if any",
"type": [
"string",
"null"
]
}
},
"required": [
"created_at",
"client_id",
"scope"
]
},
"SingleResponse_for_OAuth2Session": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_OAuth2Session"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
},
"PersonalSessionFilter": {
"type": "object",
"properties": {
"filter[owner_user]": {
"description": "Filter by owner user ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[owner_client]": {
"description": "Filter by owner `OAuth2` client ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[actor_user]": {
"description": "Filter by actor user ID",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[scope]": {
"description": "Retrieve the items with the given scope",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"filter[status]": {
"description": "Filter by session status",
"anyOf": [
{
"$ref": "#/components/schemas/PersonalSessionStatus"
},
{
"type": "null"
}
]
},
"filter[expires_before]": {
"description": "Filter by access token expiry date",
"type": [
"string",
"null"
],
"format": "date-time"
},
"filter[expires_after]": {
"description": "Filter by access token expiry date",
"type": [
"string",
"null"
],
"format": "date-time"
},
"filter[expires]": {
"description": "Filter by whether the access token has an expiry time",
"type": [
"boolean",
"null"
]
}
}
},
"PersonalSessionStatus": {
"type": "string",
"enum": [
"active",
"revoked"
]
},
"PaginatedResponse_for_PersonalSession": {
"description": "A top-level response with a page of resources",
"type": "object",
"properties": {
"meta": {
"description": "Response metadata",
"anyOf": [
{
"$ref": "#/components/schemas/PaginationMeta"
},
{
"type": "null"
}
]
},
"data": {
"description": "The list of resources",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SingleResource_for_PersonalSession"
}
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/PaginationLinks"
}
]
}
},
"required": [
"links"
]
},
"SingleResource_for_PersonalSession": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/PersonalSession"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"PersonalSession": {
"description": "A personal session (session using personal access tokens)",
"type": "object",
"properties": {
"created_at": {
"description": "When the session was created",
"type": "string",
"format": "date-time"
},
"revoked_at": {
"description": "When the session was revoked, if applicable",
"type": [
"string",
"null"
],
"format": "date-time"
},
"owner_user_id": {
"description": "The ID of the user who owns this session (if user-owned)",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"owner_client_id": {
"description": "The ID of the `OAuth2` client that owns this session (if client-owned)",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"actor_user_id": {
"description": "The ID of the user that the session acts on behalf of",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"human_name": {
"description": "Human-readable name for the session",
"type": "string"
},
"scope": {
"description": "`OAuth2` scopes for this session",
"type": "string"
},
"last_active_at": {
"description": "When the session was last active",
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_active_ip": {
"description": "IP address of last activity",
"type": [
"string",
"null"
],
"format": "ip"
},
"expires_at": {
"description": "When the current token for this session expires.\n The session will need to be regenerated, producing a new access token,\n after this time.\n None if the current token won't expire or if the session is revoked.",
"type": [
"string",
"null"
],
"format": "date-time"
},
"access_token": {
"description": "The actual access token (only returned on creation)",
"type": [
"string",
"null"
]
}
},
"required": [
"created_at",
"actor_user_id",
"human_name",
"scope"
]
},
"CreatePersonalSessionRequest": {
"title": "JSON payload for the `POST /api/admin/v1/personal-sessions` endpoint",
"type": "object",
"properties": {
"actor_user_id": {
"description": "The user this session will act on behalf of",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"human_name": {
"description": "Human-readable name for the session",
"type": "string"
},
"scope": {
"description": "`OAuth2` scopes for this session",
"type": "string"
},
"expires_in": {
"description": "Token expiry time in seconds.\n If not set, the token won't expire.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
}
},
"required": [
"actor_user_id",
"human_name",
"scope"
]
},
"SingleResponse_for_PersonalSession": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_PersonalSession"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
},
"RegeneratePersonalSessionRequest": {
"title": "JSON payload for the `POST /api/admin/v1/personal-sessions/{id}/regenerate` endpoint",
"type": "object",
"properties": {
"expires_in": {
"description": "Token expiry time in seconds.\n If not set, the token won't expire.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
}
}
},
"SetPolicyDataRequest": {
"title": "JSON payload for the `POST /api/admin/v1/policy-data`",
"type": "object",
"properties": {
"data": {
"example": {
"hello": "world",
"foo": 42,
"bar": true
}
}
},
"required": [
"data"
]
},
"SingleResponse_for_PolicyData": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_PolicyData"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
},
"SingleResource_for_PolicyData": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/PolicyData"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"PolicyData": {
"description": "The policy data",
"type": "object",
"properties": {
"created_at": {
"description": "The creation date of the policy data",
"type": "string",
"format": "date-time"
},
"data": {
"description": "The policy data content"
}
},
"required": [
"created_at",
"data"
]
},
"UserFilter": {
"type": "object",
"properties": {
"filter[admin]": {
"description": "Retrieve users with (or without) the `admin` flag set",
"type": [
"boolean",
"null"
]
},
"filter[legacy-guest]": {
"description": "Retrieve users with (or without) the `legacy_guest` flag set",
"type": [
"boolean",
"null"
]
},
"filter[search]": {
"description": "Retrieve users where the username matches contains the given string\n\n Note that this doesn't change the ordering of the result, which are\n still ordered by ID.",
"type": [
"string",
"null"
]
},
"filter[status]": {
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all users, including locked ones.\n\n * `active`: Only retrieve active users\n\n * `locked`: Only retrieve locked users (includes deactivated users)\n\n * `deactivated`: Only retrieve deactivated users",
"anyOf": [
{
"$ref": "#/components/schemas/UserStatus"
},
{
"type": "null"
}
]
}
}
},
"UserStatus": {
"type": "string",
"enum": [
"active",
"locked",
"deactivated"
]
},
"PaginatedResponse_for_User": {
"description": "A top-level response with a page of resources",
"type": "object",
"properties": {
"meta": {
"description": "Response metadata",
"anyOf": [
{
"$ref": "#/components/schemas/PaginationMeta"
},
{
"type": "null"
}
]
},
"data": {
"description": "The list of resources",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SingleResource_for_User"
}
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/PaginationLinks"
}
]
}
},
"required": [
"links"
]
},
"SingleResource_for_User": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/User"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"User": {
"description": "A user",
"type": "object",
"properties": {
"username": {
"description": "The username (localpart) of the user",
"type": "string"
},
"created_at": {
"description": "When the user was created",
"type": "string",
"format": "date-time"
},
"locked_at": {
"description": "When the user was locked. If null, the user is not locked.",
"type": [
"string",
"null"
],
"format": "date-time"
},
"deactivated_at": {
"description": "When the user was deactivated. If null, the user is not deactivated.",
"type": [
"string",
"null"
],
"format": "date-time"
},
"admin": {
"description": "Whether the user can request admin privileges.",
"type": "boolean"
},
"legacy_guest": {
"description": "Whether the user was a guest before migrating to MAS,",
"type": "boolean"
}
},
"required": [
"username",
"created_at",
"admin",
"legacy_guest"
]
},
"AddUserRequest": {
"title": "JSON payload for the `POST /api/admin/v1/users` endpoint",
"type": "object",
"properties": {
"username": {
"description": "The username of the user to add.",
"type": "string"
},
"skip_homeserver_check": {
"description": "Skip checking with the homeserver whether the username is available.\n\n Use this with caution! The main reason to use this, is when a user used\n by an application service needs to exist in MAS to craft special\n tokens (like with admin access) for them",
"type": "boolean",
"default": false
}
},
"required": [
"username"
]
},
"SingleResponse_for_User": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_User"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
},
"SetUserPasswordRequest": {
"title": "JSON payload for the `POST /api/admin/v1/users/:id/set-password` endpoint",
"type": "object",
"properties": {
"password": {
"description": "The password to set for the user",
"type": "string",
"example": "hunter2"
},
"skip_password_check": {
"description": "Skip the password complexity check",
"type": [
"boolean",
"null"
]
}
},
"required": [
"password"
]
},
"UsernamePathParam": {
"type": "object",
"properties": {
"username": {
"description": "The username (localpart) of the user to get",
"type": "string"
}
},
"required": [
"username"
]
},
"UserSetAdminRequest": {
"title": "JSON payload for the `POST /api/admin/v1/users/:id/set-admin` endpoint",
"type": "object",
"properties": {
"admin": {
"description": "Whether the user can request admin privileges.",
"type": "boolean"
}
},
"required": [
"admin"
]
},
"DeactivateUserRequest": {
"title": "JSON payload for the `POST /api/admin/v1/users/:id/deactivate` endpoint",
"type": "object",
"properties": {
"skip_erase": {
"description": "Whether to skip requesting the homeserver to GDPR-erase the user upon\n deactivation.",
"type": "boolean",
"default": false
}
}
},
"UserEmailFilter": {
"type": "object",
"properties": {
"filter[user]": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[email]": {
"description": "Retrieve the user email with the given email address",
"type": [
"string",
"null"
]
}
}
},
"PaginatedResponse_for_UserEmail": {
"description": "A top-level response with a page of resources",
"type": "object",
"properties": {
"meta": {
"description": "Response metadata",
"anyOf": [
{
"$ref": "#/components/schemas/PaginationMeta"
},
{
"type": "null"
}
]
},
"data": {
"description": "The list of resources",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SingleResource_for_UserEmail"
}
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/PaginationLinks"
}
]
}
},
"required": [
"links"
]
},
"SingleResource_for_UserEmail": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/UserEmail"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"UserEmail": {
"description": "An email address for a user",
"type": "object",
"properties": {
"created_at": {
"description": "When the object was created",
"type": "string",
"format": "date-time"
},
"user_id": {
"description": "The ID of the user who owns this email address",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"email": {
"description": "The email address",
"type": "string"
}
},
"required": [
"created_at",
"user_id",
"email"
]
},
"AddUserEmailRequest": {
"title": "JSON payload for the `POST /api/admin/v1/user-emails`",
"type": "object",
"properties": {
"user_id": {
"description": "The ID of the user to which the email should be added.",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"email": {
"description": "The email address of the user to add.",
"type": "string",
"format": "email"
}
},
"required": [
"user_id",
"email"
]
},
"SingleResponse_for_UserEmail": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_UserEmail"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
},
"UserSessionFilter": {
"type": "object",
"properties": {
"filter[user]": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[status]": {
"description": "Retrieve the items with the given status\n\n Defaults to retrieve all sessions, including finished ones.\n\n * `active`: Only retrieve active sessions\n\n * `finished`: Only retrieve finished sessions",
"anyOf": [
{
"$ref": "#/components/schemas/UserSessionStatus"
},
{
"type": "null"
}
]
}
}
},
"UserSessionStatus": {
"type": "string",
"enum": [
"active",
"finished"
]
},
"PaginatedResponse_for_UserSession": {
"description": "A top-level response with a page of resources",
"type": "object",
"properties": {
"meta": {
"description": "Response metadata",
"anyOf": [
{
"$ref": "#/components/schemas/PaginationMeta"
},
{
"type": "null"
}
]
},
"data": {
"description": "The list of resources",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SingleResource_for_UserSession"
}
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/PaginationLinks"
}
]
}
},
"required": [
"links"
]
},
"SingleResource_for_UserSession": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/UserSession"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"UserSession": {
"description": "The browser (cookie) session for a user",
"type": "object",
"properties": {
"created_at": {
"description": "When the object was created",
"type": "string",
"format": "date-time"
},
"finished_at": {
"description": "When the session was finished",
"type": [
"string",
"null"
],
"format": "date-time"
},
"user_id": {
"description": "The ID of the user who owns the session",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"user_agent": {
"description": "The user agent string of the client which started this session",
"type": [
"string",
"null"
]
},
"last_active_at": {
"description": "The last time the session was active",
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_active_ip": {
"description": "The last IP address used by the session",
"type": [
"string",
"null"
],
"format": "ip"
}
},
"required": [
"created_at",
"user_id"
]
},
"SingleResponse_for_UserSession": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_UserSession"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
},
"RegistrationTokenFilter": {
"type": "object",
"properties": {
"filter[used]": {
"description": "Retrieve tokens that have (or have not) been used at least once",
"type": [
"boolean",
"null"
]
},
"filter[revoked]": {
"description": "Retrieve tokens that are (or are not) revoked",
"type": [
"boolean",
"null"
]
},
"filter[expired]": {
"description": "Retrieve tokens that are (or are not) expired",
"type": [
"boolean",
"null"
]
},
"filter[valid]": {
"description": "Retrieve tokens that are (or are not) valid\n\n Valid means that the token has not expired, is not revoked, and has not\n reached its usage limit.",
"type": [
"boolean",
"null"
]
}
}
},
"PaginatedResponse_for_UserRegistrationToken": {
"description": "A top-level response with a page of resources",
"type": "object",
"properties": {
"meta": {
"description": "Response metadata",
"anyOf": [
{
"$ref": "#/components/schemas/PaginationMeta"
},
{
"type": "null"
}
]
},
"data": {
"description": "The list of resources",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SingleResource_for_UserRegistrationToken"
}
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/PaginationLinks"
}
]
}
},
"required": [
"links"
]
},
"SingleResource_for_UserRegistrationToken": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/UserRegistrationToken"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"UserRegistrationToken": {
"description": "A registration token",
"type": "object",
"properties": {
"token": {
"description": "The token string",
"type": "string"
},
"valid": {
"description": "Whether the token is valid",
"type": "boolean"
},
"usage_limit": {
"description": "Maximum number of times this token can be used",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
},
"times_used": {
"description": "Number of times this token has been used",
"type": "integer",
"format": "uint32",
"minimum": 0
},
"created_at": {
"description": "When the token was created",
"type": "string",
"format": "date-time"
},
"last_used_at": {
"description": "When the token was last used. If null, the token has never been used.",
"type": [
"string",
"null"
],
"format": "date-time"
},
"expires_at": {
"description": "When the token expires. If null, the token never expires.",
"type": [
"string",
"null"
],
"format": "date-time"
},
"revoked_at": {
"description": "When the token was revoked. If null, the token is not revoked.",
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"token",
"valid",
"times_used",
"created_at"
]
},
"AddUserRegistrationTokenRequest": {
"title": "JSON payload for the `POST /api/admin/v1/user-registration-tokens`",
"type": "object",
"properties": {
"token": {
"description": "The token string. If not provided, a random token will be generated.",
"type": [
"string",
"null"
]
},
"usage_limit": {
"description": "Maximum number of times this token can be used. If not provided, the\n token can be used an unlimited number of times.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
},
"expires_at": {
"description": "When the token expires. If not provided, the token never expires.",
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"SingleResponse_for_UserRegistrationToken": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_UserRegistrationToken"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
},
"EditUserRegistrationTokenRequest": {
"title": "JSON payload for the `PUT /api/admin/v1/user-registration-tokens/{id}` endpoint",
"type": "object",
"properties": {
"expires_at": {
"description": "New expiration date for the token, or null to remove expiration",
"type": [
"string",
"null"
],
"format": "date-time"
},
"usage_limit": {
"description": "New usage limit for the token, or null to remove the limit",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
}
}
},
"UpstreamOAuthLinkFilter": {
"type": "object",
"properties": {
"filter[user]": {
"description": "Retrieve the items for the given user",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[provider]": {
"description": "Retrieve the items for the given provider",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"filter[subject]": {
"description": "Retrieve the items with the given subject",
"type": [
"string",
"null"
]
}
}
},
"PaginatedResponse_for_UpstreamOAuthLink": {
"description": "A top-level response with a page of resources",
"type": "object",
"properties": {
"meta": {
"description": "Response metadata",
"anyOf": [
{
"$ref": "#/components/schemas/PaginationMeta"
},
{
"type": "null"
}
]
},
"data": {
"description": "The list of resources",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SingleResource_for_UpstreamOAuthLink"
}
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/PaginationLinks"
}
]
}
},
"required": [
"links"
]
},
"SingleResource_for_UpstreamOAuthLink": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/UpstreamOAuthLink"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"UpstreamOAuthLink": {
"description": "An upstream OAuth 2.0 link",
"type": "object",
"properties": {
"created_at": {
"description": "When the object was created",
"type": "string",
"format": "date-time"
},
"provider_id": {
"description": "The ID of the provider",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"subject": {
"description": "The subject of the upstream account, unique per provider",
"type": "string"
},
"user_id": {
"description": "The ID of the user who owns this link, if any",
"anyOf": [
{
"$ref": "#/components/schemas/ULID"
},
{
"type": "null"
}
]
},
"human_account_name": {
"description": "A human-readable name of the upstream account",
"type": [
"string",
"null"
]
}
},
"required": [
"created_at",
"provider_id",
"subject"
]
},
"AddUpstreamOauthLinkRequest": {
"title": "JSON payload for the `POST /api/admin/v1/upstream-oauth-links`",
"type": "object",
"properties": {
"user_id": {
"description": "The ID of the user to which the link should be added.",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"provider_id": {
"description": "The ID of the upstream provider to which the link is for.",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"subject": {
"description": "The subject (sub) claim of the user on the provider.",
"type": "string"
},
"human_account_name": {
"description": "A human readable account name.",
"type": [
"string",
"null"
]
}
},
"required": [
"user_id",
"provider_id",
"subject"
]
},
"SingleResponse_for_UpstreamOAuthLink": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_UpstreamOAuthLink"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
},
"UpstreamOAuthProviderFilter": {
"type": "object",
"properties": {
"filter[enabled]": {
"description": "Retrieve providers that are (or are not) enabled",
"type": [
"boolean",
"null"
]
}
}
},
"PaginatedResponse_for_UpstreamOAuthProvider": {
"description": "A top-level response with a page of resources",
"type": "object",
"properties": {
"meta": {
"description": "Response metadata",
"anyOf": [
{
"$ref": "#/components/schemas/PaginationMeta"
},
{
"type": "null"
}
]
},
"data": {
"description": "The list of resources",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SingleResource_for_UpstreamOAuthProvider"
}
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/PaginationLinks"
}
]
}
},
"required": [
"links"
]
},
"SingleResource_for_UpstreamOAuthProvider": {
"description": "A single resource, with its type, ID, attributes and related links",
"type": "object",
"properties": {
"type": {
"description": "The type of the resource",
"type": "string"
},
"id": {
"description": "The ID of the resource",
"allOf": [
{
"$ref": "#/components/schemas/ULID"
}
]
},
"attributes": {
"description": "The attributes of the resource",
"allOf": [
{
"$ref": "#/components/schemas/UpstreamOAuthProvider"
}
]
},
"links": {
"description": "Related links",
"allOf": [
{
"$ref": "#/components/schemas/SelfLinks"
}
]
},
"meta": {
"description": "Metadata about the resource",
"anyOf": [
{
"$ref": "#/components/schemas/SingleResourceMeta"
},
{
"type": "null"
}
]
}
},
"required": [
"type",
"id",
"attributes",
"links"
]
},
"UpstreamOAuthProvider": {
"description": "An upstream OAuth 2.0 provider",
"type": "object",
"properties": {
"issuer": {
"description": "The OIDC issuer of the provider",
"type": [
"string",
"null"
]
},
"human_name": {
"description": "A human-readable name for the provider",
"type": [
"string",
"null"
]
},
"brand_name": {
"description": "A brand identifier, e.g. \"apple\" or \"google\"",
"type": [
"string",
"null"
]
},
"created_at": {
"description": "When the provider was created",
"type": "string",
"format": "date-time"
},
"disabled_at": {
"description": "When the provider was disabled. If null, the provider is enabled.",
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"created_at"
]
},
"SingleResponse_for_UpstreamOAuthProvider": {
"description": "A top-level response with a single resource",
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_UpstreamOAuthProvider"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
},
"required": [
"data",
"links"
]
}
}
},
"security": [
{
"oauth2": [
"urn:mas:admin"
]
},
{
"bearer": [
"urn:mas:admin"
]
}
],
"tags": [
{
"name": "server",
"description": "Information about the server"
},
{
"name": "compat-session",
"description": "Manage compatibility sessions from legacy clients"
},
{
"name": "policy-data",
"description": "Manage the dynamic policy data"
},
{
"name": "oauth2-session",
"description": "Manage OAuth2 sessions"
},
{
"name": "user",
"description": "Manage users"
},
{
"name": "user-email",
"description": "Manage emails associated with users"
},
{
"name": "user-session",
"description": "Manage browser sessions of users"
},
{
"name": "user-registration-token",
"description": "Manage user registration tokens"
},
{
"name": "upstream-oauth-link",
"description": "Manage links between local users and identities from upstream OAuth 2.0 providers"
},
{
"name": "upstream-oauth-provider",
"description": "Manage upstream OAuth 2.0 providers"
}
]
}
Reference in New Issue View Git Blame Copy Permalink