openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys 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: API Keys
  description: API Key operations
paths:
  /api/v1/api-keys/{apikey}:
    delete:
      operationId: ApiKeys_DeleteApiKey
      tags:
      - API Keys
      summary: Revoke an API Key
      description: Revoke the current API key so that it cannot be used anymore
      parameters:
      - name: apikey
        in: path
        required: true
        description: The API Key to revoke
        schema:
          type: string
      responses:
        '200':
          description: The key has been deleted
        '404':
          description: The key is not found for this user
      security:
      - API_Key:
        - unrestricted
        Basic: []
  /api/v1/users/{idOrEmail}/api-keys/{apikey}:
    delete:
      operationId: ApiKeys_DeleteUserApiKey
      tags:
      - API Keys
      summary: Revoke an API Key of target user
      description: Revoke the API key of a target user so that it cannot be used anymore
      parameters:
      - $ref: '#/components/parameters/UserIdOrEmail'
      - name: apikey
        in: path
        required: true
        description: The API Key to revoke
        schema:
          type: string
      responses:
        '200':
          description: The key has been deleted
        '404':
          description: The key is not found for this user
      security:
      - API_Key:
        - unrestricted
        Basic: []
  /api/v1/api-keys/current:
    get:
      operationId: ApiKeys_GetCurrentApiKey
      tags:
      - API Keys
      summary: Get the current API Key information
      description: View information about the current API key
      responses:
        '200':
          description: Information about the current API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyData'
        '401':
          description: Missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - API_Key:
        - btcpay.server.canmanageusers
        Basic: []
    delete:
      operationId: ApiKeys_DeleteCurrentApiKey
      tags:
      - API Keys
      summary: Revoke the current API Key
      description: Revoke the current API key so that it cannot be used anymore
      responses:
        '200':
          description: The key was revoked and is no longer usable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyData'
        '401':
          description: Missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - API_Key: []
  /api/v1/api-keys:
    post:
      operationId: ApiKeys_CreateApiKey
      tags:
      - API Keys
      summary: Create a new API Key
      description: Create a new API Key
      responses:
        '200':
          description: Information about the new API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyData'
        '401':
          description: Missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                label:
                  type: string
                  description: The label of the new API Key
                  nullable: true
                permissions:
                  type: array
                  description: The permissions granted to this API Key (See API Key Authentication)
                  nullable: true
                  items:
                    type: string
      security:
      - API_Key:
        - unrestricted
        Basic: []
  /api/v1/users/{idOrEmail}/api-keys:
    post:
      operationId: ApiKeys_CreateUserApiKey
      tags:
      - API Keys
      summary: Create a new API Key for a user
      description: Create a new API Key for a user
      parameters:
      - $ref: '#/components/parameters/UserIdOrEmail'
      responses:
        '200':
          description: Information about the new API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyData'
        '401':
          description: Missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                label:
                  type: string
                  description: The label of the new API Key
                  nullable: true
                permissions:
                  type: array
                  description: The permissions granted to this API Key (See API Key Authentication)
                  nullable: true
                  items:
                    type: string
      security:
      - API_Key:
        - btcpay.server.canmanageusers
        Basic: []
components:
  schemas:
    ProblemDetails:
      type: object
      description: Description of an error happening during processing of the request
      properties:
        code:
          type: string
          nullable: false
          description: An error code describing the error
        message:
          type: string
          nullable: false
          description: User friendly error message about the error
    ApiKeyData:
      type: object
      additionalProperties: false
      properties:
        apiKey:
          type: string
          description: The API Key to use for API Key Authentication
          nullable: false
        label:
          type: string
          description: The label given by the user to this API Key
          nullable: false
        permissions:
          type: array
          description: The permissions associated to this API Key (can be scoped to a specific store)
          nullable: false
          items:
            type: string
          example:
          - btcpay.server.canmanageusers
          - btcpay.server.canmanageusers:2KxSpc9V5zDWfUbvgYiZuAfka4wUhGF96F75Ao8y4zHP
  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/