Standards & Concepts

Overview

BitPay provides a standards-based REST interface which enables application developers to interact in a powerful, yet secure way with their BitPay account. Using the BitPay API, clients can create and manage invoices, issue refunds, manage bills, retrieve real-time rates information, view merchant ledger entries, and much more.

Developers may call the API directly over HTTPS using the language of their choice, or take advantage of BitPay's code libraries (Java, C#, PHP, etc.)

API Contracts

BitPay considers the following types of API changes to be non-breaking and backwards-compatible:

• exposing a new resource type
• adding a new method to an existing resource type
• adding an optional property to an existing resource type
• adding an optional query parameter to an existing resource method
• deprecating an existing resource method and providing an alternative

Identities

Authentication in BitPay's API utilizes a specialized identification scheme, BitAuth Identity Protocol.

BitAuth uses the same technology in Bitcoin. A public private key pair is created using elliptic curve secp256k1. The public SIN (System identification number), like a bitcoin address, is the RIPEMD 160, SHA256 hash of the public key. See the Bitcoin Wiki for complete details:

• In each request, the client signs the full url with the request body concatenated if there is one. The signature is included in the X-Signature header and the public key is included in the X-Identity header.
• The server verifies that the signature is valid and that it matches the identity (the public key). It then computes the SIN from the public key, and sees whether that SIN has access to the requested resource.

For your convenience, all client libraries available on BitPay's GitHub account support this functionality.

API Tokens

Authorization in BitPay's API utilizes Capability-based Security principles. Each API call must be accompanied by an API Token which grants access to the requested capability. API Tokens are analagous to a real-world event ticket, which grants access to a specific event when presented at the door. Also like tickets, they may grant broad or narrow privileges (e.g. 'General Admission' vs. 'Seat 44B') as well as add bearer requirements (e.g. 'Must be over 21' or 'Non-transferrable, must show ID').

New tokens are provided with each response from the API. For example, creating a new Invoice with one token will provide a new, second token that grants access to view and interact with that Invoice exclusively. If not using BitPay's Client Libraries, you will need to keep track of these tokens on your own.

Facades

Facades grant access to collections of capabilities, such as the ability to create invoices or initiate refunds. In the ticket analogy, this corresponds to the ticket 'level', where a 'VIP' ticket would confer broader access than a 'Standard' level ticket. When registering an Identity, it is against a specific facade. Best practices suggest that the requested facade should be limited to the minimum level that grants the required capabilities.