BTCPay Server Users API

openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Users API
  version: v1
  description: "# Introduction\n\nThe BTCPay Server Greenfield API is a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Authentication\n\nYou can authenticate either via Basic Auth or an API key. It's recommended to use an API key for better security. You can create an API key in the BTCPay Server UI under `Account` -> `Manage Account` -> `API keys`. You can restrict the API key for one or multiple stores and for specific permissions. For testing purposes, you can give it the 'Unrestricted access' permission. On production you should limit the permissions to the actual endpoints you use, you can see the required permission on the API docs at the top of each endpoint under `AUTHORIZATIONS`.\n\nIf you want to simplify the process of creating API keys for your users, you can use the [Authorization endpoint](https://docs.btcpayserver.org/API/Greenfield/v1/#tag/Authorization) to predefine permissions and redirect your users to the BTCPay Server Authorization UI. You can find more information about this on the [API Authorization Flow docs](https://docs.btcpayserver.org/BTCPayServer/greenfield-authorization/) page.\n\n# Usage examples\n\nUse **Basic Auth** to read store information with cURL:\n```bash\nBTCPAY_INSTANCE=\"https://mainnet.demo.btcpayserver.org\"\nUSER=\"MyTestUser@gmail.com\"\nPASSWORD=\"notverysecurepassword\"\nPERMISSION=\"btcpay.store.canmodifystoresettings\"\nBODY=\"$(echo \"{}\" | jq --arg \"a\" \"$PERMISSION\" '. + {permissions:[$a]}')\"\n\nAPI_KEY=\"$(curl -s \\\n     -H \"Content-Type: application/json\" \\\n     --user \"$USER:$PASSWORD\" \\\n     -X POST \\\n     -d \"$BODY\" \\\n     \"$BTCPAY_INSTANCE/api/v1/api-keys\" | jq -r .apiKey)\"\n```\n\n\nUse an **API key** to read store information with cURL:\n```bash\nSTORE_ID=\"yourStoreId\"\n\ncurl -s \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Authorization: token $API_KEY\" \\\n     -X GET \\\n     \"$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID\"\n```\n\nYou can find more examples on our docs for different programming languages:\n- [cURL](https://docs.btcpayserver.org/Development/GreenFieldExample/)\n- [Javascript/Node.Js](https://docs.btcpayserver.org/Development/GreenFieldExample-NodeJS/)\n- [PHP](https://docs.btcpayserver.org/Development/GreenFieldExample-PHP/)\n\n"
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: https://{btcpay-host}
  description: Your BTCPay Server instance
  variables:
    btcpay-host:
      default: mainnet.demo.btcpayserver.org
      description: The hostname of your BTCPay Server instance
security:
- API_Key: []
  Basic: []
tags:
- name: Users
  description: User operations
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: []
    put:
      tags:
      - Users
      summary: Update current user information
      description: Update the current user
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                email:
                  type: string
                  description: The email of the user
                  nullable: true
                name:
                  type: string
                  description: The name of the user
                  nullable: true
                imageUrl:
                  type: string
                  description: The profile picture URL of the user
                  nullable: true
                currentPassword:
                  type: string
                  description: The current password of the user
                  nullable: true
                newPassword:
                  type: string
                  description: The new password of the user
                  nullable: true
        required: true
        x-position: 1
      operationId: Users_UpdateCurrentUser
      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.canmodifyprofile
        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/me/picture:
    post:
      tags:
      - Users
      summary: Uploads a profile picture for the current user
      description: Uploads a profile picture for the current user
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              properties:
                file:
                  type: string
                  description: The profile picture
                  format: binary
      operationId: Users_UploadCurrentUserProfilePicture
      responses:
        '200':
          description: Uploads a profile picture for the current user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationUserData'
        '404':
          description: The user could not be found
      security:
      - API_Key:
        - btcpay.user.canmodifyprofile
        Basic: []
    delete:
      tags:
      - Users
      summary: Deletes user profile picture
      description: Deletes the user profile picture
      operationId: Users_DeleteCurrentUserProfilePicture
      responses:
        '200':
          description: Profile picture deleted successfully
        '404':
          description: The user could not be found
      security:
      - API_Key:
        - btcpay.user.canmodifyprofile
        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.


        This operation can be called without authentication in any of this cases:

        * There is not any administrator yet on the server,

        * User registrations are not disabled in the server''s policies.


        If the first administrator is created by this call, user registrations 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
                name:
                  type: string
                  description: The name of the new user
                  nullable: true
                imageUrl:
                  type: string
                  description: The profile picture URL of the new user
                  nullable: true
                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
                sendInvitationEmail:
                  type: boolean
                  description: Flag to specify if an email invitation should be sent to the user
                  nullable: true
                  default: true
        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 user 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:
      - $ref: '#/components/parameters/UserIdOrEmail'
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationUserData'
        '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.


        Must be an admin to perform this operation.


        Attempting to delete the only admin user will not succeed.


        All data associated with the user will be deleted as well if the operation succeeds.'
      parameters:
      - $ref: '#/components/parameters/UserIdOrEmail'
      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.


        Must be an admin to perform this operation.


        Attempting to lock the only admin user will not succeed.'
      parameters:
      - $ref: '#/components/parameters/UserIdOrEmail'
      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.


        Must be an admin to perform this operation.


        Attempting to (un)approve a user for which this requirement does not exist will not succeed.'
      parameters:
      - $ref: '#/components/parameters/UserIdOrEmail'
      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
        name:
          type: string
          description: The name of the user
          nullable: true
        imageUrl:
          type: string
          description: The profile picture URL of the user
          nullable: true
        invitationUrl:
          type: string
          description: The pending invitation URL of the user
          nullable: true
        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
        storeQuota:
          type: number
          nullable: true
          description: Per-user override for the max number of stores this user can create. Null means the server default applies
        created:
          type: number
          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'
        disabled:
          type: boolean
          description: True if an admin has disabled the user
        roles:
          type: array
          nullable: false
          items:
            type: string
          description: The roles of the user
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
    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
    ValidationProblemDetails:
      type: array
      description: An array of validation errors of the request
      items:
        type: object
        description: A specific validation error on a json property
        properties:
          path:
            type: string
            nullable: false
            description: The json path of the property which failed validation
          message:
            type: string
            nullable: false
            description: User friendly error message about the validation
  parameters:
    UserIdOrEmail:
      name: idOrEmail
      in: path
      required: true
      description: The user's id or email
      schema:
        type: string
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'BTCPay Server API key. Format: ''token {apiKey}'''
    Basic:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with email and password
externalDocs:
  description: Check out our examples on how to use the API
  url: https://docs.btcpayserver.org/Development/GreenFieldExample/