Authentication

Every request to the Sotirea API carries an API key, sent as a bearer token:

GET /v1/me HTTP/1.1
Host: api.sotirea.com
Authorization: Bearer sot_test_REPLACE_WITH_YOUR_KEY

A request without a key, or with one that is malformed, revoked or expired, is answered 401 with the code unauthenticated; for a key that has expired, fields.rule says api_key_expired. GET /v1/me is the simplest way to check a key: it answers the key’s name, its organisation, whether that is Test or Live, and the permissions it holds.

Test keys and Live keys

A key reaches exactly one organisation. A key starting sot_test_ reaches your Test organisation, where every network is a test network. A key starting sot_live_ reaches your Live organisation and real money. Your Test and Live organisations are separate: a Test key can never see or move anything in Live, and the other way round.

The prefix is also there for secret scanners. A key ends in a short checksum, so a scanner can tell a real Sotirea key from a string that only looks like one, and a mistyped key is refused at once.

Creating a key

Keys are created in the console, under Developers and API keys, by someone who can manage roles. A key holds roles, as a person does, and can do what those roles allow and nothing more. You can only give a key a role whose permissions you hold yourself.

For a key that runs an integration, the Integration role is the usual choice. It opens vaults, requests payments and manages webhooks, and it can see balances, payments, payment rules and the gas pool. Any role that can move money, Integration included, takes effect only once a second person who can manage roles confirms it. In an organisation where nobody else could confirm it, it takes effect at once.

Some things a key can never do, whatever its roles: it never approves a payment, and it never manages people or roles. Those stay with people, so that software alone cannot both ask for a payment and agree to it.

When you create a key you choose how long it works: 30 days, 90 days, a year, or until it is revoked.

The key is shown once

Sotirea keeps only a fingerprint of a key, never the key itself, so it cannot show it to you again. Put it straight into your server’s environment or secrets manager. Never put a key in a web page, a mobile app or a repository: anyone who can read it can use it.

What each permission allows

Each operation in the API reference needs one permission, and a key without it is answered 403 with the code forbidden and the missing permission in fields.rule, such as payments.request. GET /v1/me needs none.

• View balances balances.view

  See vaults, addresses and what each holds.

  • What each vault holds, per asset and network
  • Money that came in, newest first
  • The networks your organisation can use
  • How a refresh went
  • A statement for a period, as CSV
  • Your vaults, with the address to pay each one on every network
  • One vault and its addresses
  • Ask the networks again what a vault holds

• View payments payments.view

  See payments, their status and who requested and approved them.

  • What is known about an address before you pay it
  • Payments out of your vaults, newest first
  • One payment, by its id

• Request payments payments.request

  Ask for money to be sent from the organisation’s vaults. Payment rules may still require approval.

  • Pay out of a vault
  • What sending a payment now would come to, with nothing sent
  • Stop a stuck payment
  • Send a stuck payment again with a higher network fee

• View payment rules rules.view

  See the limits and approvals the organisation’s payments are held to.

  • Your organisation's approved addresses
  • Your organisation's payment rules
  • Your organisation's sweeps, with how each last ran

• Manage approved destinations destinations.manage

  Add or remove the addresses payments may be sent to.

  • Take an address off the approved list
  • Add an address to the approved list

• View the gas pool gas.view

  See the coin set aside to pay network fees.

  • The coin set aside to pay network fees, on each network

• View the audit trail audit.view

  See the record of who did what, and export it.

  • Your organisation's audit trail, newest first

• Manage sweeps sweeps.manage

  Set the rules that gather money from deposit vaults into one of the organisation’s own vaults.

  • Propose a sweep, or a change to one
  • What one sweep would cost now
  • Propose stopping a sweep
  • Withdraw a proposal this key made

• Open vaults vaults.manage

  Open new vaults and name them. Opening a vault moves no money.

  • Open a vault, or have back the one with this reference

• Manage webhooks webhooks.manage

  Choose the addresses Sotirea tells when a payment, a deposit or a gas pool changes, and see what was sent to them.

  • The kinds of event a webhook can be sent
  • Your webhooks
  • Add a webhook; its signing secret is in this answer only
  • Stop sending to a webhook and remove it
  • One webhook and its recent deliveries
  • Send one delivery again
  • Turn a webhook Sotirea turned off back on
  • Give a webhook a new signing secret

Limiting a key to your servers

On a key’s page in the console, under Where it can be used from, you can list the addresses your servers call from: single IP addresses or ranges in CIDR form, IPv4 or IPv6. A request from anywhere else is answered 403, with fields.rule set to api_key_address. A new key works from anywhere until you limit it.

If your servers have fixed outbound addresses, limit every Live key to them. A key that leaks is then useless anywhere else.

Replacing a key

To replace a key’s secret without stopping your integration, roll it from its page. You get a new secret at once and choose how long the old one keeps working: not at all, an hour, a day or a week. Deploy the new secret within that time and the old one stops on its own. Roll a key with no overlap at all if you think it has leaked, or revoke it.

Nobody can roll a key that can do something they cannot do themselves, because the new secret would let them do it.

Keeping keys safe

• Keep keys on your server. A browser or a phone app can be read by whoever holds it.
• Give each service its own key, named for it. Payments a key requests are shown under its name, so you can always tell which service asked.
• Give a key only the roles it needs. A service that only reads balances needs Viewer, not Integration.
• Use a Test key everywhere except the one place that handles real money.