openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Lightning address 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: Lightning address
  description: Lightning address configuration
paths:
  /api/v1/stores/{storeId}/lightning-addresses:
    get:
      tags:
      - Lightning address
      summary: Get store configured lightning addresses
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: Get store configured lightning addresses
      operationId: StoreLightningAddresses_GetStoreLightningAddresses
      responses:
        '200':
          description: The lightning addresses configured in the store
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LightningAddressData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
  /api/v1/stores/{storeId}/lightning-addresses/{username}:
    get:
      tags:
      - Lightning address
      summary: Get store configured lightning address
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: username
        in: path
        required: true
        description: The lightning address username
        schema:
          type: string
      description: Get store configured lightning address
      operationId: StoreLightningAddresses_GetStoreLightningAddress
      responses:
        '200':
          description: The lightning address configured in the store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LightningAddressData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
    post:
      tags:
      - Lightning address
      summary: Add or update store configured lightning address
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: username
        in: path
        required: true
        description: the lightning address username
        schema:
          type: string
      description: Add or update store configured lightning address
      operationId: StoreLightningAddresses_AddOrUpdateStoreLightningAddress
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LightningAddressData'
        required: true
        x-position: 1
      responses:
        '200':
          description: The lightning address configured in the store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LightningAddressData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
    delete:
      tags:
      - Lightning address
      summary: Remove configured lightning address
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: username
        in: path
        required: true
        description: The lightning address username
        schema:
          type: string
      description: Remove store configured lightning address
      operationId: StoreLightningAddresses_RemoveStoreLightningAddress
      responses:
        '200':
          description: Lightning address removed
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
components:
  schemas:
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    LightningAddressData:
      type: object
      additionalProperties: false
      properties:
        username:
          type: string
          description: The username of the lightning address
        currencyCode:
          type: string
          nullable: true
          description: The currency to generate the invoices for this lightning address in. Leave null lto use the store default.
        min:
          type: string
          nullable: true
          description: The minimum amount in sats this ln address allows
        max:
          type: string
          nullable: true
          description: The maximum amount in sats this ln address allows
        invoiceMetadata:
          type: object
          nullable: true
          description: The invoice metadata as JSON.
  parameters:
    StoreId:
      name: storeId
      in: path
      required: true
      description: The store ID
      schema:
        $ref: '#/components/schemas/StoreId'
  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/