Access Control

The first is who may call the API at all. That is decided at the team level, by the role attached to a credential, and it is described on this page.

The second is who may move a particular kind of token out of a particular account. That is decided inside the ledger, by the keys named on each account and asset and the quorum of signatures each requires. A credential with full read-write access still cannot transfer tokens it holds no key for.

Access control at the team level covers two surfaces:

• Console - available to people via a web browser with an email and password.
• Ledger API - available to people and systems via an SDK with an API credential.

PeopleLink to this section

People are human users on your team who can reach the console and the Ledger API.

AccountsLink to this section

An account belongs to an email address and carries a role. The person signs in at /{team}/login — teams are path segments, so acme signs in at /acme/login — with that address and a password they set themselves.

Addresses are unique within a team rather than globally, so the same address can hold an account on more than one team.

Signing up creates a team and its first account, an administrator.

After that, an administrator adds people from the Team page in the console. An invitation names an address and a role, and the emailed link is good for seven days. Accepting it sets a password and hands over a credential that was minted when the invitation was sent, so accepting grants nothing that was not already granted.

Roles are changed and people are removed from the same page. Removing somebody deletes every credential they hold, and that is what revokes access rather than the account record disappearing: a console session is a credential replayed on each request, so it stops working at once instead of lasting until they sign out. A team cannot be left with nobody able to administer it, so its last administrator can be neither demoted nor removed.

Personal API CredentialsLink to this section

People developing against a ledger reach the Ledger API from their own machines with a personal API credential: a single opaque string, 32 characters of base32. It carries the role of the person it was issued to, and the core checks that role on every call.

Create one on the API keys page in the console. Anybody may create their own, because a credential carries the role they already hold and so grants nothing new; an administrator may also create one for anybody else on the team, and sees the team's whole list. A member holds at most ten at a time.

A credential is printed once, when it is created, and cannot be retrieved afterwards — only a digest of it is stored, by the core and by the console alike. Treat one as you would a password. If it leaks, revoke it from the same page and create another; that changes nothing about the ledger itself, because a credential decides who may call the API, not who may move tokens.

The credential your console session uses is held sealed in an httpOnly cookie and forwarded to the core on your behalf, so it is never shown to the browser. It appears in your key list, marked, because revoking it signs you out — a console session is a credential replayed on each request. A credential for use from your own machine is a separate one, created for that purpose.

SystemsLink to this section

Systems are non-human callers on your team — your staging and production environments, a settlement service, a reporting job — that reach the Ledger API and never the console.

A system uses a credential of its own rather than a person's, so that its access can be scoped and revoked without touching anybody's sign-in, and so that the credential that acted is identifiable afterwards. A system is created the same way as a person's account, minus the console sign-in: it has a role, and one or more credentials carrying it.

In practice an administrator invites an address for the system, chooses the role it should have, and creates its credentials from the API keys page. Giving a settlement job its own readwrite identity rather than a credential belonging to whoever set it up is what makes "who did this" answerable a year later, and what lets that person leave without taking the job down.

RolesLink to this section

A role is an access control policy assigned to a person or a system. It defines what they can do in the console and through the Ledger API, and it applies to every credential issued to them.

There are currently three roles:

• Admin

  • Everything in readwrite and readonly, plus
  • Can create and edit access controls (people, systems, and roles)

• Readwrite

  • Everything in readonly, plus
  • Can create and edit ledgers
  • Can create and edit objects inside ledgers (keys, accounts, assets, and feeds)
  • Can sign transactions (to transfer and issue tokens)

• Readonly

  • Can view ledgers
  • Can view objects inside ledgers (keys, accounts, assets, and feeds)
  • Can query ledger data (transactions, actions, and tokens)
  • Can read a feed, but not acknowledge it — acknowledging moves the feed's position, which is a write

A role is the ceiling, not the grant. Readwrite is what lets a caller submit a transaction at all; whether that transaction is accepted still depends on whether it carries the signatures the accounts and assets it touches require.

A role also applies to a whole ledger. Read access is not scoped to particular accounts or assets, so anyone who can query a ledger can query all of it. Where two parties should not see each other's balances, give them separate ledgers rather than separate roles on one.