{ "openapi": "3.1.0", "info": { "title": "Matrix Authentication Service admin API", "version": "" }, "servers": [ { "url": "{base}", "variables": { "base": { "default": "/", "description": null } } } ], "paths": { "/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", "$ref": "#/components/schemas/ULID", "nullable": true }, "style": "form" }, { "in": "query", "name": "page[after]", "description": "Retrieve the items after the given ID", "schema": { "description": "Retrieve the items after the given ID", "$ref": "#/components/schemas/ULID", "nullable": true }, "style": "form" }, { "in": "query", "name": "page[first]", "description": "Retrieve the first N items", "schema": { "description": "Retrieve the first N items", "type": "integer", "format": "uint", "minimum": 1.0, "nullable": true }, "style": "form" }, { "in": "query", "name": "page[last]", "description": "Retrieve the last N items", "schema": { "description": "Retrieve the last N items", "type": "integer", "format": "uint", "minimum": 1.0, "nullable": true }, "style": "form" }, { "in": "query", "name": "filter[can_request_admin]", "description": "Retrieve users with (or without) the `can_request_admin` flag set", "schema": { "description": "Retrieve users with (or without) the `can_request_admin` flag set", "type": "boolean", "nullable": true }, "style": "form" }, { "in": "query", "name": "filter[status]", "description": "Retrieve the items with the given status\n\nDefaults to retrieve all users, including locked ones.\n\n* `active`: Only retrieve active users\n\n* `locked`: Only retrieve locked users", "schema": { "description": "Retrieve the items with the given status\n\nDefaults to retrieve all users, including locked ones.\n\n* `active`: Only retrieve active users\n\n* `locked`: Only retrieve locked users", "$ref": "#/components/schemas/UserStatus", "nullable": true }, "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, "can_request_admin": false }, "links": { "self": "/api/admin/v1/users/01040G2081040G2081040G2081" } }, { "type": "user", "id": "02081040G2081040G2081040G2", "attributes": { "username": "bob", "created_at": "1970-01-01T00:00:00Z", "locked_at": null, "can_request_admin": true }, "links": { "self": "/api/admin/v1/users/02081040G2081040G2081040G2" } }, { "type": "user", "id": "030C1G60R30C1G60R30C1G60R3", "attributes": { "username": "charlie", "created_at": "1970-01-01T00:00:00Z", "locked_at": "1970-01-01T00:00:00Z", "can_request_admin": false }, "links": { "self": "/api/admin/v1/users/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": { "200": { "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, "can_request_admin": 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, "can_request_admin": 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/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, "can_request_admin": 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" } ] } } } } } } } }, "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" } } } } }, "schemas": { "PaginationParams": { "type": "object", "properties": { "page[before]": { "description": "Retrieve the items before the given ID", "$ref": "#/components/schemas/ULID", "nullable": true }, "page[after]": { "description": "Retrieve the items after the given ID", "$ref": "#/components/schemas/ULID", "nullable": true }, "page[first]": { "description": "Retrieve the first N items", "type": "integer", "format": "uint", "minimum": 1.0, "nullable": true }, "page[last]": { "description": "Retrieve the last N items", "type": "integer", "format": "uint", "minimum": 1.0, "nullable": true } } }, "ULID": { "title": "ULID", "description": "A ULID as per https://github.com/ulid/spec", "examples": [ "01ARZ3NDEKTSV4RRFFQ69G5FAV", "01J41912SC8VGAQDD50F6APK91" ], "type": "string", "pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$" }, "UserFilter": { "type": "object", "properties": { "filter[can_request_admin]": { "description": "Retrieve users with (or without) the `can_request_admin` flag set", "type": "boolean", "nullable": true }, "filter[status]": { "description": "Retrieve the items with the given status\n\nDefaults to retrieve all users, including locked ones.\n\n* `active`: Only retrieve active users\n\n* `locked`: Only retrieve locked users", "$ref": "#/components/schemas/UserStatus", "nullable": true } } }, "UserStatus": { "type": "string", "enum": [ "active", "locked" ] }, "PaginatedResponse_for_User": { "description": "A top-level response with a page of resources", "type": "object", "required": [ "data", "links", "meta" ], "properties": { "meta": { "description": "Response metadata", "$ref": "#/components/schemas/PaginationMeta" }, "data": { "description": "The list of resources", "type": "array", "items": { "$ref": "#/components/schemas/SingleResource_for_User" } }, "links": { "description": "Related links", "$ref": "#/components/schemas/PaginationLinks" } } }, "PaginationMeta": { "type": "object", "required": [ "count" ], "properties": { "count": { "description": "The total number of results", "type": "integer", "format": "uint", "minimum": 0.0 } } }, "SingleResource_for_User": { "description": "A single resource, with its type, ID, attributes and related links", "type": "object", "required": [ "attributes", "id", "links", "type" ], "properties": { "type": { "description": "The type of the resource", "type": "string" }, "id": { "description": "The ID of the resource", "$ref": "#/components/schemas/ULID" }, "attributes": { "description": "The attributes of the resource", "$ref": "#/components/schemas/User" }, "links": { "description": "Related links", "$ref": "#/components/schemas/SelfLinks" } } }, "User": { "description": "A user", "type": "object", "required": [ "can_request_admin", "created_at", "username" ], "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", "format": "date-time", "nullable": true }, "can_request_admin": { "description": "Whether the user can request admin privileges.", "type": "boolean" } } }, "SelfLinks": { "description": "Related links", "type": "object", "required": [ "self" ], "properties": { "self": { "description": "The canonical link to the current resource", "type": "string" } } }, "PaginationLinks": { "description": "Related links", "type": "object", "required": [ "first", "last", "self" ], "properties": { "self": { "description": "The canonical link to the current page", "type": "string" }, "first": { "description": "The link to the first page of results", "type": "string" }, "last": { "description": "The link to the last page of results", "type": "string" }, "next": { "description": "The link to the next page of results\n\nOnly present if there is a next page", "type": "string", "nullable": true }, "prev": { "description": "The link to the previous page of results\n\nOnly present if there is a previous page", "type": "string", "nullable": true } } }, "ErrorResponse": { "description": "A top-level response with a list of errors", "type": "object", "required": [ "errors" ], "properties": { "errors": { "description": "The list of errors", "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "Error": { "description": "A single error", "type": "object", "required": [ "title" ], "properties": { "title": { "description": "A human-readable title for the error", "type": "string" } } }, "AddUserRequest": { "title": "JSON payload for the `POST /api/admin/v1/users` endpoint", "type": "object", "required": [ "username" ], "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\nUse this with caution! The main reason to use this, is when a user used by an application service needs to exist in MAS to craft special tokens (like with admin access) for them", "default": false, "type": "boolean" } } }, "SingleResponse_for_User": { "description": "A top-level response with a single resource", "type": "object", "required": [ "data", "links" ], "properties": { "data": { "$ref": "#/components/schemas/SingleResource_for_User" }, "links": { "$ref": "#/components/schemas/SelfLinks" } } }, "UlidInPath": { "type": "object", "required": [ "id" ], "properties": { "id": { "title": "The ID of the resource", "$ref": "#/components/schemas/ULID" } } }, "UsernamePathParam": { "type": "object", "required": [ "username" ], "properties": { "username": { "description": "The username (localpart) of the user to get", "type": "string" } } } } }, "security": [ { "oauth2": [ "urn:mas:admin" ] } ], "tags": [ { "name": "user", "description": "Manage users" } ] }