API keys

An API key lets an Interledger client, such as a script using ilp-plugin-btp, connect to your node and send and receive payments with your money. Here is how to make one, cap it and take it back.

What a key is

The wallet calls them API keys and BTP tokens: the same thing. Each token belongs to one of your ledgers. A client that connects with it pays out of your money on that ledger, and what it receives is yours too. Anyone who has the token can do that, so treat it like a password, and give it a cap unless you trust the client with everything on that ledger.

Apps that work through Open Payments do not need a key: they ask for a grant, which you approve in the wallet. See Connect apps.

Create a key

1. Open Settings, and find the API keys card.
2. Under Create BTP token, give it a Label you will recognize later, such as the client's name. It is at most 64 characters.
3. Choose the Ledger, by its ID, such as hub-xrpl-testnet-xrp+xrp. The client pays and is paid in that ledger's currency.
4. Set a Spending cap and how often it renews, Per hour, day or week. Leave the amount empty for no cap.
5. Select Create BTP token.
6. A dialog shows the Token and the URL. Select Copy BTP URL and put it in your client's configuration.

The URL holds the token and your node's address:

btp+wss://:<token>@node.example.com/btp

A node that serves HTTPS on another port than 443 has the port in the URL too. On a node without a domain name, such as the desktop app, the URL names localhost, so the client has to run on the same machine. To connect a client, see Connect an ILP client over BTP.

A key connects clients only while your node runs the ledger it belongs to. A key whose ledger does not run, such as one of a scheme your node no longer offers, stays listed for you to see and revoke, but no client connects with it.

Caps

A cap is the most a key may spend per hour, day or week. It refills smoothly rather than all at once: a key capped at 10 a day that spent 10 has about 5 again twelve hours later. Over any stretch of time, a key spends at most its cap once, plus the cap's share of the time that passed.

• Only money that leaves you counts: payments out to your peers. Paying your own node, or another key's client, moves none of your money out, and does not count.
• Payments still under way count as spent, until they finish.
• All of a key's connections share its one cap.
• A payment that would go over the cap is refused. The client sees an Interledger error: T04 while the cap is used up, or F08 for a single packet larger than the whole cap. See Error codes.

Each key in the list shows its cap, such as Cap: XRP 10.00 per day, a meter of how much is used, and how much is left. Select Set a cap or Edit cap to change it, or Remove cap to lift it. A cap you set is in the ledger's currency.

Why it works this way: how a cap refills, and what counts against it.

Reading the list

Each key shows its label, its ledger, when you made it, how many clients are connected with it now, and what it received net: what came in through it less what went out, negative once it has spent more than it took in. A label left empty shows as unnamed.

Revoke a key

1. Find the key in the API keys card.
2. Select Revoke, and confirm.

Its clients are disconnected, and from that moment they can send no new payments. The key is refused from then on. Payments it already made stay made, and its history stays in your books.

If a client keeps failing to log in, your node slows it down: it limits failed logins per address. Clients that log in successfully can reconnect as often as they need.