Every Management API call carries Authorization: Bearer <token>. There are two kinds of caller, and they obtain that token in completely different ways: Both end up as a bearer token whose role decides what the caller may do — the roles and permissions model below is the same for both.
In both cases the token is a Cognito ID token, not an access token. The API rejects access tokens.

​
Service users (machine-to-machine)

A service user is a machine identity in your program. Orenda provisions it and gives you USERNAME, PASSWORD, ClientId, and the client secret used to compute SECRET_HASH — one set per environment, so the credential you use decides whether you are hitting live or sandbox.
Token issuance is IP-allowlisted. Give Orenda support the egress IP or range of the backend that will authenticate, before you start.

​
Get a token

Use AuthenticationResult.IdToken as your bearer token. It is valid for about an hour; renew it with the returned RefreshToken (AuthFlow: "REFRESH_TOKEN_AUTH") rather than re-sending the password on every call.

​
What the token can call

The Management API documented on this site, at https://api.next.orenda.finance. Calls are scoped to a program with the programId query parameter and authorised against your service user’s role, exactly like an operator’s.

​
Step-up (SCA) exemption

Endpoints that normally require a step-up confirmation — passkey or TOTP — recognise a service-user session and skip the challenge, since no human is present to answer it. Today that applies to POST /v1/access-management/invite/customer: send the invite without a confirmation object and it succeeds, where an operator would get 422 SCA_MISSING. Everything else is unchanged: the endpoint still has to be permitted by the service user’s role.

​
Operator sign-in

Operators authenticate through the same auth endpoints as customers — there is no separate back-office login. What makes a session an operator session is the role it carries.
  1. POST /v1/auth/login with email + password, and the x-program-id header.
  2. Complete the 2FA challenge with POST /v1/auth/verify-2fa (TOTP). Operators are expected to have 2FA set up; use POST /v1/auth/mfa/setup + confirm on first login.
  3. Use the returned token as Authorization: Bearer <token> on every Management API call.

​
Roles and permissions

The role on the token determines what the caller can do — some roles administer a whole program, others are scoped to a subset of its customers. Service users are assigned a role the same way, so a machine identity can only act on the customers it is scoped to. Roles and their permissions are configured by Orenda when your access is set up. If a call you expect to be allowed returns 403, ask Orenda to adjust the role rather than changing the request. Your token’s own profile and role — type: "SOFTWARE_USER" for a service user, type: "BO_USER" for an operator — is not self-served; ask Orenda if you need it confirmed.