btcpayserver/BTCPayServer/wwwroot/swagger/v1/swagger.template.json

388 lines
16 KiB
JSON
Raw Normal View History

2020-03-18 20:08:09 +09:00
{
"openapi": "3.0.0",
"info": {
"title": "BTCPay Greenfield API",
"description": "A full API to use your BTCPay Server",
"contact": {
"name": "BTCPay Server",
"url": "https://btcpayserver.org",
"email": "nicolas.dorier@gmail.com"
},
"version": "v1"
},
"servers": [
],
"paths": {
"/api-keys/authorize": {
"get": {
"tags": [
"Authorization"
],
"summary": "Authorize User",
"description": "Redirect the browser to this endpoint to request the user to generate an api-key with specific permissions",
2020-03-18 20:51:50 +09:00
"operationId": "Manage_AuthorizeAPIKey",
2020-03-18 20:08:09 +09:00
"parameters": [
{
"name": "permissions",
2020-03-18 23:30:27 +09:00
"description": "The permissions to request. (See APIKey authentication)",
2020-03-18 20:08:09 +09:00
"in": "query",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"x-position": 1
},
{
"name": "applicationName",
"description": "The name of your application",
"in": "query",
"schema": {
"type": "string",
"nullable": true
},
"x-position": 2
},
{
"name": "strict",
"description": "If permissions are specified, and strict is set to false, it will allow the user to reject some of permissions the application is requesting.",
"in": "query",
"schema": {
"type": "boolean",
"default": true
},
"x-position": 3
},
{
"name": "selectiveStores",
"description": "If the application is requesting the CanModifyStoreSettings permission and selectiveStores is set to true, this allows the user to only grant permissions to selected stores under the user's control.",
"in": "query",
"schema": {
"type": "boolean",
"default": false
},
"x-position": 4
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
},
"security": [
{
"APIKey": []
}
]
}
},
"/api/v1/users/me": {
"get": {
"tags": [
"Users"
],
"summary": "Get current user information",
"description": "View information about the current user",
2020-03-18 20:51:50 +09:00
"operationId": "Users_GetCurrentUser",
2020-03-18 20:08:09 +09:00
"responses": {
"200": {
"description": "Information about the current user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationUserData"
}
}
}
}
},
"security": [
{
"APIKey": [
"ProfileManagement"
2020-03-18 20:08:09 +09:00
]
}
]
}
},
"/api/v1/users": {
"post": {
"tags": [
"Users"
],
"summary": "Create user",
"description": "Create a new user. This operation can be called without authentication if there is not any administrator yet on the server.",
2020-03-18 20:08:09 +09:00
"requestBody": {
"x-name": "request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"email": {
"type": "string",
2020-03-18 23:35:17 +09:00
"description": "The email of the new user",
"nullable": false
2020-03-18 20:08:09 +09:00
},
"password": {
2020-03-18 23:35:17 +09:00
"type": "string",
"description": "The password of the new user"
2020-03-18 20:08:09 +09:00
},
"isAdministrator": {
"type": "boolean",
2020-03-20 18:38:21 +09:00
"description": "Make this user administrator (only if your APIKey has `unrestricted` permission of a server administrator)",
"nullable": true,
"default": false
2020-03-18 20:08:09 +09:00
}
}
}
}
},
"required": true,
"x-position": 1
},
"responses": {
"201": {
"description": "Information about the new user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApplicationUserData"
}
}
}
2020-03-18 20:51:50 +09:00
},
"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 ServerManagement permission)"
},
"429": {
"description": "DDoS protection if you are creating more than 2 accounts every minutes (non-admin only)"
2020-03-18 20:08:09 +09:00
}
},
"security": [
{
"APIKey": [
"ServerManagement"
],
"Anonymous": [ ]
2020-03-18 20:08:09 +09:00
}
]
}
},
"/api/v1/api-keys/current": {
"get": {
"tags": [
"API Keys"
],
"summary": "Get current API Key information",
"description": "View information about the current API key",
2020-03-18 20:51:50 +09:00
"operationId": "ApiKeys_GetKey",
2020-03-18 20:08:09 +09:00
"responses": {
"200": {
"description": "Information about the current api key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiKeyData"
}
}
}
}
},
"security": [
{
"APIKey": []
}
]
},
"delete": {
"tags": [
"API Keys"
],
"summary": "Revoke the current API Key",
"description": "Revoke the current API key so that it cannot be used anymore",
2020-03-18 20:51:50 +09:00
"operationId": "ApiKeys_RevokeKey",
"responses": {
"200": {
"description": "The key was revoked and is no longer usable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiKeyData"
}
}
}
}
},
"security": [
{
"APIKey": []
}
]
}
2020-03-18 20:08:09 +09:00
}
},
"components": {
"schemas": {
"ApplicationUserData": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
2020-03-18 23:35:17 +09:00
"description": "The id of the new user",
"nullable": false
2020-03-18 20:08:09 +09:00
},
"email": {
"type": "string",
2020-03-18 23:35:17 +09:00
"description": "The email of the new user",
"nullable": false
2020-03-18 20:08:09 +09:00
},
"emailConfirmed": {
2020-03-18 23:35:17 +09:00
"type": "boolean",
"description": "True if the email has been confirmed by the user"
2020-03-18 20:08:09 +09:00
},
"requiresEmailConfirmation": {
2020-03-18 23:35:17 +09:00
"type": "boolean",
"description": "True if the email requires email confirmation to log in"
2020-03-18 20:08:09 +09:00
}
}
},
2020-03-18 20:51:50 +09:00
"ValidationProblemDetails": {
"allOf": [
{
"$ref": "#/components/schemas/ProblemDetails"
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"errors": {
"type": "object",
"nullable": true,
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
]
},
"ProblemDetails": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"type": "integer",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
},
"extensions": {
"type": "object",
"nullable": true,
"additionalProperties": {}
}
}
},
2020-03-18 20:08:09 +09:00
"ApiKeyData": {
"type": "object",
"additionalProperties": false,
"properties": {
"apiKey": {
"type": "string",
"nullable": true
},
"label": {
"type": "string",
"nullable": true
},
"userId": {
"type": "string",
"nullable": true
},
"permissions": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
}
}
}
},
"securitySchemes": {
"APIKey": {
"type": "apiKey",
2020-03-20 14:33:11 +09:00
"description": "BTCPay Server supports authenticating and authorizing users through an API Key that is generated by them. Send the API Key as a header value to Authorization with the format: token {token}. For a smoother experience, you can generate a url that redirects users to an API key creation screen.\n\n The following permissions applies to the context of the user creating the API Key:\n * `unrestricted`: Allow unrestricted access to your account.\n * `btcpay.server.canmodifyserversettings`: Allow total control on the server settings. (only if user is administrator)\n * `btcpay.server.cancreateuser`: Allow the creation new users on this server. (only if user is administrator)\n * `btcpay.user.canviewprofile`: Allow view access to your user profile.\n * `btcpay.user.canmodifyprofile`: Allow view and modification access to your user profile.\n\nThe following permissions applies to all stores of the user, you can limit to a specific store with the following format: `btcpay.store.cancreateinvoice:6HSHAEU4iYWtjxtyRs9KyPjM9GAQp8kw2T9VWbGG1FnZ`:\n * `btcpay.store.canviewstoresettings`: Allow view access to the stores settings. \n * `btcpay.store.canmodifystoresettings`: Allow view and modification access to the stores settings.\n * `btcpay.store.cancreateinvoice`: Allow invoice creation of the store.\n\nNote that API Keys only limits permission of a user and can never expand it. If an API Key has the permission `btcpay.server.canmodifyserversettings` but that the user account creating this API Key is not administrator, the API Key will not be able to modify the server settings.\n",
2020-03-18 20:08:09 +09:00
"name": "Authorization",
"in": "header"
2020-03-18 23:30:27 +09:00
},
"Anonymous": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Nothing required",
"description": "Anonymous authentication"
2020-03-18 20:08:09 +09:00
}
}
},
"security": [
{
2020-03-18 23:30:27 +09:00
"APIKey": [],
"Anonymous": []
2020-03-18 20:08:09 +09:00
}
],
"tags": [
{
"name": "Users"
},
{
"name": "API Keys"
}
]
}