mirror of
https://github.com/btcpayserver/btcpayserver.git
synced 2025-02-23 14:40:36 +01:00
6290b0f3bf
* Users list: Cleanups * Policies: Flip registration settings * Policies: Add RequireUserApproval setting * Add approval to user * Require approval on login and for API key * API handling * AccountController cleanups * Test fix * Apply suggestions from code review Co-authored-by: Nicolas Dorier <nicolas.dorier@gmail.com> * Add missing imports * Communicate login requirements to user on account creation * Add login requirements to basic auth handler * Cleanups and test fix * Encapsulate approval logic in user service and log approval changes * Send follow up "Account approved" email Closes #5656. * Add notification for admins * Fix creating a user via the admin view * Update list: Unify flags into status column, add approve action * Adjust "Resend email" wording * Incorporate feedback from code review * Remove duplicate test server policy reset --------- Co-authored-by: Nicolas Dorier <nicolas.dorier@gmail.com>
438 lines
18 KiB
JSON
438 lines
18 KiB
JSON
{
|
|
"paths": {
|
|
"/api/v1/users/me": {
|
|
"get": {
|
|
"tags": [
|
|
"Users"
|
|
],
|
|
"summary": "Get current user information",
|
|
"description": "View information about the current user",
|
|
"operationId": "Users_GetCurrentUser",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Information about the current user",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApplicationUserData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "The user could not be found"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.user.canviewprofile"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Users"
|
|
],
|
|
"summary": "Deletes user profile",
|
|
"description": "Deletes user profile and associated user data for user making the request",
|
|
"operationId": "Users_DeleteCurrentUser",
|
|
"responses": {
|
|
"200": {
|
|
"description": "User and associated data deleted successfully"
|
|
},
|
|
"404": {
|
|
"description": "The user could not be found"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.user.candeleteuser"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/users": {
|
|
"get": {
|
|
"operationId": "Users_GetUsers",
|
|
"tags": [
|
|
"Users"
|
|
],
|
|
"summary": "Get all users",
|
|
"description": "Load all users that exist.",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Users found"
|
|
},
|
|
"401": {
|
|
"description": "Missing authorization for loading the users"
|
|
},
|
|
"403": {
|
|
"description": "Authorized but forbidden to load the users. You have the wrong API permissions."
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.server.canviewusers"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
},
|
|
"post": {
|
|
"operationId": "Users_CreateUser",
|
|
"tags": [
|
|
"Users"
|
|
],
|
|
"summary": "Create user",
|
|
"description": "Create a new user.\n\nThis operation can be called without authentication in any of this cases:\n* There is not any administrator yet on the server,\n* The subscriptions are not disabled in the server's policies.\n\nIf the first administrator is created by this call, subscriptions are automatically disabled.",
|
|
"requestBody": {
|
|
"x-name": "request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"email": {
|
|
"type": "string",
|
|
"description": "The email of the new user",
|
|
"nullable": false
|
|
},
|
|
"password": {
|
|
"type": "string",
|
|
"description": "The password of the new user (if no password is set, an email will be sent to the user requiring him to set the password)",
|
|
"nullable": true
|
|
},
|
|
"isAdministrator": {
|
|
"type": "boolean",
|
|
"description": "Make this user administrator (only if you have the `unrestricted` permission of a server administrator)",
|
|
"nullable": true,
|
|
"default": false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"required": true,
|
|
"x-position": 1
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Information about the new user",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApplicationUserData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "A list of errors that occurred when creating the user",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"description": "If you need to authenticate for this endpoint (ie. the server settings policies lock subscriptions and that an admin already exists)"
|
|
},
|
|
"403": {
|
|
"description": "If you are authenticated but forbidden to create a new user (ie. you don't have the `unrestricted` permission on a server administrator or if you are not administrator and registrations are disabled in the server's policies)"
|
|
},
|
|
"429": {
|
|
"description": "DDoS protection if you are creating more than 2 accounts every minutes (non-admin only)"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.server.cancreateuser"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/users/{idOrEmail}": {
|
|
"get": {
|
|
"operationId": "Users_GetUser",
|
|
"tags": [
|
|
"Users"
|
|
],
|
|
"summary": "Get user by ID or Email",
|
|
"description": "Get 1 user by ID or Email.",
|
|
"parameters": [
|
|
{
|
|
"name": "idOrEmail",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID or email of the user to load",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "User found"
|
|
},
|
|
"401": {
|
|
"description": "Missing authorization for loading the user"
|
|
},
|
|
"403": {
|
|
"description": "Authorized but forbidden to load the user. You have the wrong API permissions."
|
|
},
|
|
"404": {
|
|
"description": "No user found with this ID or email"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.server.canviewusers"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
},
|
|
"delete": {
|
|
"operationId": "Users_DeleteUser",
|
|
"tags": [
|
|
"Users"
|
|
],
|
|
"summary": "Delete user",
|
|
"description": "Delete a user.\n\nMust be an admin to perform this operation.\n\nAttempting to delete the only admin user will not succeed.\n\nAll data associated with the user will be deleted as well if the operation succeeds.",
|
|
"parameters": [
|
|
{
|
|
"name": "idOrEmail",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID or email of the user to be deleted",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "User has been successfully deleted"
|
|
},
|
|
"401": {
|
|
"description": "Missing authorization for deleting the user"
|
|
},
|
|
"403": {
|
|
"description": "Authorized but forbidden to delete the user. Can happen if you attempt to delete the only admin user."
|
|
},
|
|
"404": {
|
|
"description": "User with provided ID was not found"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.user.candeleteuser"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/users/{idOrEmail}/lock": {
|
|
"post": {
|
|
"operationId": "Users_ToggleUserLock",
|
|
"tags": [
|
|
"Users"
|
|
],
|
|
"summary": "Toggle user lock out",
|
|
"description": "Lock or unlock a user.\n\nMust be an admin to perform this operation.\n\nAttempting to lock the only admin user will not succeed.",
|
|
"parameters": [
|
|
{
|
|
"name": "idOrEmail",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the user to be un/locked",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"x-name": "request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/LockUserRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "User has been successfully toggled"
|
|
},
|
|
"401": {
|
|
"description": "Missing authorization for locking the user"
|
|
},
|
|
"403": {
|
|
"description": "Authorized but forbidden to lock the user. Can happen if you attempt to disable the only admin user."
|
|
},
|
|
"404": {
|
|
"description": "User with provided ID was not found"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.user.canmodifyserversettings"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/users/{idOrEmail}/approve": {
|
|
"post": {
|
|
"operationId": "Users_ToggleUserApproval",
|
|
"tags": [
|
|
"Users"
|
|
],
|
|
"summary": "Toggle user approval",
|
|
"description": "Approve or unapprove a user.\n\nMust be an admin to perform this operation.\n\nAttempting to (un)approve a user for which this requirement does not exist will not succeed.",
|
|
"parameters": [
|
|
{
|
|
"name": "idOrEmail",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the user to be un/approved",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"x-name": "request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApproveUserRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "User has been successfully toggled"
|
|
},
|
|
"401": {
|
|
"description": "Missing authorization for approving the user"
|
|
},
|
|
"403": {
|
|
"description": "Authorized but forbidden to approve the user. Can happen if you attempt to set the status of a user that does not have the approval requirement."
|
|
},
|
|
"404": {
|
|
"description": "User with provided ID was not found"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.user.canmodifyserversettings"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"schemas": {
|
|
"ApplicationUserData": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "The id of the user",
|
|
"nullable": false
|
|
},
|
|
"email": {
|
|
"type": "string",
|
|
"description": "The email of the user",
|
|
"nullable": false
|
|
},
|
|
"emailConfirmed": {
|
|
"type": "boolean",
|
|
"description": "True if the email has been confirmed by the user"
|
|
},
|
|
"requiresEmailConfirmation": {
|
|
"type": "boolean",
|
|
"description": "True if the email requires confirmation to log in"
|
|
},
|
|
"approved": {
|
|
"type": "boolean",
|
|
"description": "True if an admin has approved the user"
|
|
},
|
|
"requiresApproval": {
|
|
"type": "boolean",
|
|
"description": "True if the instance requires approval to log in"
|
|
},
|
|
"created": {
|
|
"nullable": true,
|
|
"description": "The creation date of the user as a unix timestamp. Null if created before v1.0.5.6",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/UnixTimestamp"
|
|
}
|
|
]
|
|
},
|
|
"roles": {
|
|
"type": "array",
|
|
"nullable": false,
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "The roles of the user"
|
|
}
|
|
}
|
|
},
|
|
"LockUserRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"locked": {
|
|
"type": "boolean",
|
|
"description": "Whether to lock or unlock the user"
|
|
}
|
|
}
|
|
},
|
|
"ApproveUserRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"approved": {
|
|
"type": "boolean",
|
|
"description": "Whether to approve or unapprove the user"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"tags": [
|
|
{
|
|
"name": "Users",
|
|
"description": "User operations"
|
|
}
|
|
]
|
|
}
|