openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Authorization 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: Authorization
  description: Authorization operations
paths:
  /api-keys/authorize:
    get:
      operationId: ApiKeys_Authorize
      tags:
      - Authorization
      summary: Authorize User
      description: Redirect the browser to this endpoint to request the user to generate an api-key with specific permissions
      parameters:
      - name: permissions
        description: The permissions to request. (See API Key authentication)
        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
          nullable: 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
          nullable: true
        x-position: 4
      - name: redirect
        description: 'The url to redirect to after the user consents, with the query parameters appended to it: permissions, user-id, api-key. If not specified, user is redirected to their API Key list.'
        in: query
        schema:
          type: string
          format: url
          nullable: true
        x-position: 5
      - name: applicationIdentifier
        description: If specified, BTCPay Server will check if there is an existing API key associated with the user that also has this application identifier, redirect host AND the permissions required match(takes selectiveStores and strict into account). `applicationIdentifier` is ignored if redirect is not specified.
        in: query
        schema:
          type: string
          nullable: true
        x-position: 6
      responses:
        '200':
          description: A HTML form that a user can use to confirm permissions to grant
          content:
            text/html: {}
        '307':
          description: Makes browser do an HTTP POST request to the specified url in `redirect` with a JSON body consisting of `apiKey` (the api key created or matched), `permissions` (the permissions the user consented to), and `userId` (the id of the user that consented) upon consent
        '401':
          description: Missing authorization
          content:
            text/html: {}
      security: []
components:
  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/