Keys and tokens
Ripple has two kinds of key: a send key sends, and an API token reads and manages. Most scripts only send, and need nothing more than a send key.
Which one you need
| Send key | API token | |
|---|---|---|
| Can | Send to its own source | Read, and with full access, send and change anything |
| Looks like | rpl_send_… | rpl_api_… |
| Find it in | The source's menu or settings | Settings → Developer |
| Copy it again | Any time | Never; only when you add it |
| Stops working | When you reset it | When you remove it, or after 180 days unused |
| If it leaks | Someone can post to that source | Someone can read your messages, and with full access, change or delete them |
Either one goes in the same header:
The examples in these docs, and the CLI, read the key from RIPPLE_KEY.
Send keys
Every source has its own send key, Inbox included. In Ripple's sidebar, open the source's menu and choose Copy send key. The key is also in the source's settings.
The key already knows its source, so a send doesn't need to name one. A send that names a different source gets 400 invalid_source.
Send from a tool that only takes a URL
Some tools, such as another service's webhook settings, take a URL but no headers. For those, choose Copy send address from the send key's menu. It copies an address with the key in it:
This works only for sending, only as a POST, and only with a send key. Put the key in the header or the address, never both.
Addresses end up in logs and browser history, and the key goes with them. Use the header whenever the tool allows it.
Reset a send key
If a key may have leaked, replace it. In the source's settings, choose Reset key from the send key's menu. Ripple copies the new key, and the old one stops working at once, so update every tool that used it.
API tokens
Add one token for each machine or job, so you can remove one without breaking the rest.
- Open Settings → Developer.
- Under API tokens, choose Add token.
- Name it after where it runs, such as “Backup server”.
- Choose its access, then copy the token.
Copy the token while Ripple shows it. Ripple keeps only a fingerprint, so it can't show the token again.
Choose its access
- Full access, the default, can use every operation in the API reference, including sending to any source, getting and resetting send keys, and deleting messages and sources for good.
- Read only can list, read and search messages, threads, sources and Trash, and nothing else. It suits a dashboard, a backup or a report.
A read-only token that tries anything else gets 403 read_only_token, and nothing changes. Access is fixed when you add a token. To change it, add a new token and remove the old one.
Remove a token
The API tokens list shows when each token was last used. Choose Remove to end one at once. A token unused for 180 days ends on its own.
Some things stay in the signed-in app on purpose: account settings, sign-in, API tokens themselves, devices and sync.
When a key is turned away
| Response | What it means |
|---|---|
401 | The key is missing, mistyped, reset or removed. A send key also gets 401 for anything but sending, since reading and managing need an API token. |
403 read_only_token | A read-only token tried to change something. Use a token with full access. |