BTCPay Server Users API

openapi: 3.2.0
info:
  title: BTCPay Greenfield Users API
  version: v1
  description: '# Introduction


    The 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.


    # Authentication


    You 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`.


    If you want to simplify the process of creating API keys for your users, you can use the Authorization endpoint 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 page.


    # Usage examples


    Use **Basic Auth** to read store information with cURL:

    ```bash

    BTCPAY_INSTANCE="https://mainnet.demo.btcpayserver.org"

    USER="MyTestUser@gmail.com"

    PASSWORD="notverysecurepassword"

    PERMISSION="btcpay.store.canmodifystoresettings"

    BODY="$(echo "{}" | jq --arg "a" "$PERMISSION" ''. + {permissions:[$a]}'')"


    API_KEY="$(curl -s \

    -H "Content-Type: application/json" \

    --user "$USER:$PASSWORD" \

    -X POST \

    -d "$BODY" \

    "$BTCPAY_INSTANCE/api/v1/api-keys" | jq -r .apiKey)"

    ```


    Use an **API key** to read store information with cURL:

    ```bash

    STORE_ID="yourStoreId"


    curl -s \

    -H "Content-Type: application/json" \

    -H "Authorization: token $API_KEY" \

    -X GET \

    "$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID"

    ```


    You can find more examples on our docs for different programming languages:

    - cURL

    - Javascript/Node.Js

    - PHP'
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: /
  description: BTCPay Server Greenfield API
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
                  - 'null'
                  description: The email of the user
                name:
                  type:
                  - string
                  - 'null'
                  description: The name of the user
                imageUrl:
                  type:
                  - string
                  - 'null'
                  description: The profile picture URL of the user
                currentPassword:
                  type:
                  - string
                  - 'null'
                  description: The current password of the user. Required when changing the email or the password.
                newPassword:
                  type:
                  - string
                  - 'null'
                  description: The new password of the user
                allowGreenfieldBasicAuth:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to allow Basic authentication for the Greenfield API
        required: true
        x-position: 1
      operationId: Users_UpdateCurrentUser
      responses:
        '200':
          description: Information about the current user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationUserData'
        '422':
          description: Unable to validate the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '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
      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
                name:
                  type:
                  - string
                  - 'null'
                  description: The name of the new user
                imageUrl:
                  type:
                  - string
                  - 'null'
                  description: The profile picture URL of the new user
                password:
                  type:
                  - string
                  - 'null'
                  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)
                isAdministrator:
                  type:
                  - boolean
                  - 'null'
                  description: Make this user administrator (only if you have the `unrestricted` permission of a server administrator)
                  default: false
                sendInvitationEmail:
                  type:
                  - boolean
                  - 'null'
                  description: Flag to specify if an email invitation should be sent to the user
                  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:
    ApproveUserRequest:
      type: object
      additionalProperties: false
      properties:
        approved:
          type: boolean
          description: Whether to approve or unapprove the user
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
    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
            description: The json path of the property which failed validation
          message:
            type: string
            description: User friendly error message about the validation
    ApplicationUserData:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: The id of the user
        email:
          type: string
          description: The email of the user
        name:
          type:
          - string
          - 'null'
          description: The name of the user
        imageUrl:
          type:
          - string
          - 'null'
          description: The profile picture URL of the user
        invitationUrl:
          type:
          - string
          - 'null'
          description: The pending invitation URL of the user
        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
          - 'null'
          description: Per-user override for the max number of stores this user can create. Null means the server default applies
        created:
          type:
          - number
          - 'null'
          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
        allowGreenfieldBasicAuth:
          type: boolean
          description: Whether Basic authentication is allowed for the Greenfield API
        roles:
          type: array
          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
  parameters:
    UserIdOrEmail:
      name: idOrEmail
      in: path
      required: true
      description: The user's id or email
      schema:
        type: string
  securitySchemes:
    API_Key:
      type: apiKey
      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 are available to the context of the user creating the API Key:\n\n* `btcpay.impersonation.canimpersonate`: Can impersonate users\n* `btcpay.user.candeleteuser`: Delete user\n* `btcpay.user.canmanagenotificationsforuser`: Manage your notifications\n* `btcpay.user.canmodifyprofile`: Manage your profile\n* `btcpay.user.canviewnotificationsforuser`: View your notifications\n* `btcpay.user.canviewprofile`: View your profile\n* `unrestricted`: Unrestricted access\n\nThe following permissions are available if the user is an administrator:\n\n* `btcpay.server.cancreatelightninginvoiceinternalnode`: Create invoices with internal lightning node\n* `btcpay.server.cancreateuser`: Create new users\n* `btcpay.server.canmanageusers`: Manage users\n* `btcpay.server.canmodifyserversettings`: Manage your server\n* `btcpay.server.canuseinternallightningnode`: Use the internal lightning node\n* `btcpay.server.canviewlightninginvoiceinternalnode`: View invoices from internal lightning node\n* `btcpay.server.canviewusers`: View users\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\n* `btcpay.store.canarchivepullpayments`: Archive your pull payments\n* `btcpay.store.canbroadcasttransactions`: Broadcast wallet transactions\n* `btcpay.store.cancanceltransactions`: Cancel wallet transactions\n* `btcpay.store.cancreateinvoice`: Create an invoice\n* `btcpay.store.cancreatelightninginvoice`: Create invoices from the lightning nodes associated with your stores\n* `btcpay.store.cancreatenonapprovedpullpayments`: Create non-approved pull payments\n* `btcpay.store.cancreatepullpayments`: Create pull payments\n* `btcpay.store.cancreatetransactions`: Create wallet transactions\n* `btcpay.store.cancreditsubscribers`: Credit your subscribers\n* `btcpay.store.canmanageinvoicestatus`: Manage invoice status\n* `btcpay.store.canmanagelegacyaccesstokens`: Manage legacy access tokens\n* `btcpay.store.canmanagepayouts`: Manage payouts\n* `btcpay.store.canmanagepullpayments`: Manage your pull payments\n* `btcpay.store.canmanagesubscribers`: Manage your subscribers\n* `btcpay.store.canmanagewallets`: Manage wallets\n* `btcpay.store.canmanagewalletsettings`: Manage wallet settings\n* `btcpay.store.canmanagewallettransactions`: Manage wallet transactions\n* `btcpay.store.canmodifyinvoices`: Modify invoices\n* `btcpay.store.canmodifyofferings`: Modify your offerings\n* `btcpay.store.canmodifypaymentrequests`: Modify your payment requests\n* `btcpay.store.canmodifystoresettings`: Modify your stores\n* `btcpay.store.cansendstoreemails`: Send store emails\n* `btcpay.store.cansigntransactions`: Sign wallet transactions\n* `btcpay.store.canuselightningnode`: Use the lightning nodes associated with your stores\n* `btcpay.store.canviewinvoices`: View invoices\n* `btcpay.store.canviewlightninginvoice`: View the lightning invoices associated with your stores\n* `btcpay.store.canviewofferings`: View your offerings\n* `btcpay.store.canviewpaymentrequests`: View your payment requests\n* `btcpay.store.canviewpayouts`: View payouts\n* `btcpay.store.canviewpullpayments`: View your pull payments\n* `btcpay.store.canviewreports`: View your reports\n* `btcpay.store.canviewstoresettings`: View your stores\n* `btcpay.store.canviewwallet`: View wallets\n* `btcpay.store.webhooks.canmodifywebhooks`: Modify stores webhooks\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.\nSome permissions may include other permissions, see [this operation](#operation/permissionsMetadata).\n"
      name: Authorization
      in: header
    Basic:
      type: http
      description: BTCPay Server supports authenticating and authorizing users through the Basic HTTP authentication scheme during the first five minutes after account creation or when the user explicitly enables it. Send the user and password encoded in base64 with the format `Basic {base64(username:password)}`. Using this authentication method implicitly provides you with the `unrestricted` permission
      scheme: Basic
externalDocs:
  description: BTCPay Greenfield Plugins API
  url: https://docs.btcpayserver.org/API/Greenfield/Plugins/
x-provenance:
  method: harvested
  publisher: BTCPay Server
  source: https://docs.btcpayserver.org/API/Greenfield/v1/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)