BTCPay Server Stores (Users) API

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


    The BTCPay Server Greenfield API is a REST API.'
  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: Stores (Users)
  description: Store Users operations
paths:
  /api/v1/stores/{storeId}/users:
    get:
      tags:
      - Stores (Users)
      summary: Get store users
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: View users of the specified store
      operationId: Stores_GetStoreUsers
      responses:
        '200':
          description: specified store users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreUserDataList'
        '403':
          description: If you are authenticated but forbidden to view the specified store's users
        '404':
          description: The store could not be found
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
    post:
      tags:
      - Stores (Users)
      summary: Add a store user
      operationId: Stores_AddStoreUser
      parameters:
      - $ref: '#/components/parameters/StoreId'
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreUserData'
        required: true
        x-position: 1
      responses:
        '200':
          description: The user was added
        '400':
          description: A list of errors that occurred when adding the store user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to add new store users
        '404':
          description: The store or user could not be found
        '409':
          description: 'Error code: `duplicate-store-user-role`. Removing this user would result in the store having no owner.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
  /api/v1/stores/{storeId}/users/{idOrEmail}:
    put:
      tags:
      - Stores (Users)
      summary: Updates a store user
      operationId: Stores_UpdateStoreUser
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/UserIdOrEmail'
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreUserData'
        required: true
        x-position: 1
      responses:
        '200':
          description: The user was updated
        '400':
          description: A list of errors that occurred when updating the store user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to update store users
        '404':
          description: The store or user could not be found
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
    delete:
      tags:
      - Stores (Users)
      summary: Remove Store User
      operationId: Stores_RemoveStoreUser
      description: Removes the specified store user. If there is no other owner, this endpoint will fail.
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/UserIdOrEmail'
      responses:
        '200':
          description: The user has been removed
        '400':
          description: A list of errors that occurred when removing the store user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '409':
          description: 'Error code: `store-user-role-orphaned`. Removing this user would result in the store having no owner.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: If you are authenticated but forbidden to remove the specified store user
        '404':
          description: The store or user could not be found
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
components:
  parameters:
    StoreId:
      name: storeId
      in: path
      required: true
      description: The store ID
      schema:
        $ref: '#/components/schemas/StoreId'
    UserIdOrEmail:
      name: idOrEmail
      in: path
      required: true
      description: The user's id or email
      schema:
        type: string
  schemas:
    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
        roles:
          type: array
          items:
            type: string
          description: The roles of the user
    StoreUserData:
      allOf:
      - type: object
        properties:
          userId:
            type: string
            description: The id of the user (Deprecated, use `id` instead)
            deprecated: true
          role:
            type: string
            description: The role of the user. Default roles are `Owner`, `Manager`, `Employee` and `Guest` (Deprecated, use `storeRole` instead)
            deprecated: true
          storeRole:
            type: string
            description: The role of the user. Default roles are `Owner`, `Manager`, `Employee` and `Guest`
      - $ref: '#/components/schemas/ApplicationUserData'
    StoreUserDataList:
      type: array
      items:
        $ref: '#/components/schemas/StoreUserData'
    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
    ProblemDetails:
      type: object
      description: Description of an error happening during processing of the request
      properties:
        code:
          type: string
          description: An error code describing the error
        message:
          type: string
          description: User friendly error message about the error
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
  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/