Privacy policy ↗

Authentication and Authorization

Authentication

All non-public endpoints require authentication. A few public endpoints work without credentials. Two mechanisms are supported.

Bearer tokens

Bearer tokens are for registered users. The user logs in with their credentials and receives an access token, which goes in the Authorization header:

curl https://api.arratech.com/orgs/<ORG_ID>/transactions/<TRANSACTION_ID> \
  -H 'Authorization: Bearer <access_token>'

The login response also contains a refresh token. There is no endpoint for refreshing a token. Contact Arratech support for lifecycle guidance.

API keys

API keys are for machine-to-machine access. An organisation admin generates them, and they are sent in the X-API-Key header:

curl https://api.arratech.com/orgs/<ORG_ID>/transactions/<TRANSACTION_ID> \
  -H 'X-API-Key: <api_key>'

Things to know:

  • A key has a role, orgmember or orgadmin, set when the key is created. Everything done with the key is done with that role, so give each key the lowest role that does the job.
  • A key can have an expiry date. Without one it never expires. A key marked inactive always fails authentication.
  • The full key is returned once, when you create it. After that the API only shows a masked value, so store the key securely straight away.

Authorization

Every authenticated caller has a role. Each endpoint has a lowest role, and a request is only allowed if the caller's role is high enough.

A user who logs in has one of two roles: superadmin or user. A user who acts on behalf of an organisation they are a member of also has a member role: orgadmin or orgmember. The roles, from highest to lowest access:

  • superadmin: full access across the whole system. Reserved for Arratech staff.
  • orgadmin: full access within one organisation. Manages members, participants, access points, certificates and API keys for the organisation and its child organisations.
  • orgmember: limited access within one organisation. Can do some things on the organisation's behalf, for example send a document.
  • user: authenticated, but not tied to an organisation. Can edit their own profile or create an organisation.
  • public: anonymous. Only open endpoints, such as lookup.

The lowest role for each endpoint is shown in the API reference.

Multi-factor authentication (MFA)

MFA adds a second step at login. Two methods are supported: TOTP (a rotating 6-digit code from an authenticator app) and SMS (a code sent to the user's phone). MFA is set up per user.

  • TOTP: set up in two steps. First you get a secret to scan or enter in your authenticator app. Then you confirm with a code from the app.
  • SMS: add a phone number to your profile, then enable SMS MFA.
  • Login: when MFA is on, logging in does not return tokens. It returns a challenge. Answer it with the 6-digit code to get the same tokens as a normal login.

An organisation admin can require MFA for every member of the organisation. While that is on, members cannot disable MFA. An admin can only switch the requirement on once MFA is enabled on their own account.

In the API reference