Authentication and Authorization

Authentication

All non-public endpoints in the Arratech API require authentication. Only a few public endpoints are accessible without credentials. Authenticated access is supported through two mechanisms:

Bearer tokens

Bearer tokens are for registered users. The user authenticates with his/her credentials and receives a token, which must be included in the Authorization header:

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


API tokens

API tokens are for machine-to-machine access. Organisations can generate API tokens, which typically are used for machine-to-machine systems or services. The token is included in requests using the X-Api-Key header:

curl -X GET https://api.arratech.com/orgs/<ORG_ID>/transactions/<TRANSACTION_ID>' \ 
  -H "X-Api-Key: <api_token>"

API token can have role orgmember and orgadmin and it is set upon creation of it.

Authorization

All authenticated users in the Arratech solution have assigned roles. Furthermore, each API endpoint has a defined role level. When a user makes a request to an API endpoint, the user's role is evaluated towards the endpoint's role level and the request is only authorized if the user's role is high enough.

The end user roles are: ‘superadmin’ and ‘user’. Each user that logs in via the API has one of these roles. Furthermore, when a user acts on behalf of an organisation in which he/she is member he/she has one of the member roles: 'orgadmin' or 'orgmember'.

The following roles, in order from highest level of access to lowest, are available in Arratech Solution:

superadmin
  • Scope: Full access across the entire system.
  • Description: Reserved for Arratech personnel. Can manage all organisations, users, and system-level resources.
orgadmin
  • Scope: Full access within a single organisation.
  • Description: Can manage members, member roles, participants, endpoints, certificates for Access Point(s) and SMP(s), and API keys for their organisation and child organisations.
orgmember
  • Scope: Limited access within a single organisation.
  • Description: Can perform some operations on behalf of the organisation, e.g. initiate a document transaction.
user
  • Scope: Authenticated user access without relation to a specific organisation.
  • Description: Access to operations that require authentication but unrelated to organisations. E.g. modify the user profile, create a new organisation.
public
  • Scope: Anonymous access.
  • Description: Unauthenticated callers. Only permitted to access open or public endpoints (e.g. metadata, health checks, or discovery services).

Multi-Factor Authentication (MFA)

MFA adds a second verification step at login, on top of the username and password. Two methods are supported: TOTP (a rotating 6-digit code from an authenticator app) and SMS (a code sent to the user's phone). Both are configured per user. Organisations can require MFA for all members — see Org-level enforcement below.

Setting up TOTP

TOTP setup is a two-step process. You need an authenticator app (Google Authenticator, Authy, or equivalent).

  1. Associate: POST /users/me/mfa/totp/associate — returns a secretCode and an otpauth:// URI you can render as a QR code. This endpoint requires the raw Cognito access token (the bearer token from login) in the Authorization header.
  2. Verify: POST /users/me/mfa/totp/verify — submit the 6-digit code from your authenticator app to activate TOTP on the account.

Setting up SMS MFA

Set a phone number on your profile first via PUT /users/me, then call POST /users/me/mfa/sms/enable to enable SMS MFA. Cognito verifies the phone number automatically after the first successful SMS challenge.

Checking MFA status

GET /users/me/mfa/status returns the enabled methods, available methods, and whether a phone number is present for SMS. See the User endpoint page for the full MFA endpoint list.

Login flow with MFA enabled

When MFA is active on an account, POST /users/login does not return tokens. Instead it returns a challenge response containing a session string and a challengeName of either SOFTWARE_TOKEN_MFA (TOTP) or SMS_MFA.

Complete the login by calling POST /users/login/mfa-challenge with the following body:

  • username — the user's email address
  • challengeName — SOFTWARE_TOKEN_MFA or SMS_MFA
  • session — the session string from the login response
  • mfaCode — the 6-digit code from the authenticator app or SMS

On success, the response contains the full token set — the same as a normal login.

Org-level enforcement

An org admin can require MFA for all organisation members by setting mfaRequired: true on the organisation via PUT /orgs/:orgId. While this flag is set, members cannot disable MFA and must have at least one MFA method active. See the Users, Members and Organisations page for details on organisation management.

Disabling MFA

DELETE /users/me/mfa removes all MFA methods from the account. This call is blocked if the user belongs to any organisation with mfaRequired: true — the API returns an error identifying the organisation(s) enforcing the requirement.

Arratech API – Auth & MFA Summary

Authentication Methods

  • Bearer tokens (for registered users)
    • Obtain via POST /users/login.
    • Use in Authorization header:
      • Authorization: Bearer <access_token>
  • API tokens (for machine-to-machine)
    • Created at org level, role is fixed at creation: orgmember or orgadmin.
    • Use in X-Api-Key header:
      • X-Api-Key: <api_token>

Public (unauthenticated) endpoints include:

  • POST /users/signup
  • POST /users/login
  • Open metadata, health checks, discovery like GET /lookup

Token refresh:

  • Login returns accessToken and refreshToken.
  • No public refresh endpoint; contact Arratech support for lifecycle guidance.

Authorization & Roles (highest → lowest)

  • superadmin
    • Scope: Entire system.
    • Use: Arratech staff; manage all orgs, users, system resources.
  • orgadmin
    • Scope: Single organisation (and children).
    • Can manage: members, roles, participants, endpoints, AP/SMP certs, API keys.
  • orgmember
    • Scope: Limited within one organisation.
    • Can perform some org operations (e.g. initiate document transactions).
  • user
    • Scope: Authenticated user, not tied to an org.
    • Can manage own profile, create orgs, etc.
  • public
    • Scope: Anonymous.