A User is a person with access to a Tenant - invited by email, with a role that determines what they can see and do. Users are separate from the System User your backend uses for machine-to-machine calls.
How provisioning actually works in practice: create tenants using your System User, not a personal account - that's the supported pattern. To give a person access, invite them (POST .../user_memberships/invite with their email and a role) rather than trying to create a User directly - POST /users exists in the API, but isn't available to a System User token in practice (it returns 403). Accepting the invitation is what actually creates the Ason User and membership; the invitee does that themselves, not you. There's also no way to link one person to several tenants at once - send a separate invitation per tenant, and the invitee accepts each one individually.
FAQ
Do I need one Ason user per employee?
No - end users of an embedded integration typically don't need individual Ason users; see Authenticating from a Backend for the recommended pattern.
How do I invite someone to a tenant?
POST .../user_memberships/invite with { email, role } - see API Endpoints below.
Can my System User create a new user directly via POST /users?
Not in practice - it returns 403 for a System User token, even though the endpoint exists in the API. Use the invite flow instead: invite by email, and the person creates their own User by accepting the invitation - you never call POST /users yourself.
Is there a way to attach an existing user to a tenant without sending an invitation?
Yes - POST /tenants/{orgId}/user_memberships takes an existing userId directly and creates the membership immediately. But it only works if that person already has an Ason User record; for someone new, use the invite flow instead.
Can an Owner-level token invite someone as Admin?
No documented role-hierarchy restriction was found on the invite endpoint - Owner and Admin are treated as equivalent for permissions elsewhere in the API, so a System User provisioned at Owner level should be able to invite someone as Admin.
How does someone actually accept an invitation?
Either through the link they're given (in the sandbox: https://sandbox.asonpayroll.com/invitation/{invitationId}), or programmatically via POST /user_membership_invitations/{invitationId} - called with the invitee's own token, not the inviter's.
Can I give one person access to several tenants at once?
No - invite them separately to each tenant, and they have to accept each invitation individually. There's no bulk or shared invite across tenants.
Should tenants be created with a personal user or the System User?
The System User - that's the recommended, supported pattern for anything programmatic.
What's the difference between a User and a System User?
A User is a person with interactive access; a System User is a machine-to-machine credential for your backend.
How does a user actually register/log in?
Through your connected Identity & Access Management provider (IAM/OIDC) - accepting an invitation (POST /user_membership_invitations/{invitationId}) links that IAM account to a tenant. Ason itself doesn't run its own signup/login screen.
Does a user need two-factor authentication?
That's governed entirely by your IAM/OIDC provider (e.g. Zitadel), not by Ason - configure it there if you need it.
Can I change an existing user's name, email or password?
Not through Ason - those belong to your IAM provider. The only thing a user can change in Ason itself is their language/culture setting (PUT /users/{userId}).
How do I remove a user?
DELETE /tenants/{orgId}/user_memberships/{userMembershipId} - this removes their access to the tenant, not their underlying IAM account.
What types of users exist?
Regular Users (interactive, invited by email) and System Users (machine-to-machine, for your backend) - see Authenticating from a Backend.
How does a normal "frontend" user work?
They're invited by email, log in via your IAM/OIDC connection, and see CaseMan scoped to whatever role they were given.
What roles exist for a normal frontend user, and what does each see?
- Administrator - full access to the whole tenant
- Manager - access limited to the specific payrolls they're assigned to
- Self Service - access limited to their own employee record only (linked to a specific Employee), landing directly on their own ESS documents
Can I change a user's role after inviting them?
Yes - PUT /tenants/{orgId}/user_memberships/{userMembershipId} updates the role (and which employee it's linked to, for Self Service).
API Endpoints
| What | Call |
|---|---|
| Get the current user | GET /users |
| Update a user | PUT /users/{userId} |
| Create a user (not usable by a System User token in practice) | POST /users |
| List user memberships (who has access) | GET /tenants/{orgId}/user_memberships |
| Attach an existing user to a tenant directly | POST /tenants/{orgId}/user_memberships |
| List pending invitations | GET /tenants/{orgId}/user_memberships/invitations |
| Update a member's role | PUT /tenants/{orgId}/user_memberships/{userMembershipId} |
| Remove a member | DELETE /tenants/{orgId}/user_memberships/{userMembershipId} |
| Invite a user | POST /tenants/{orgId}/user_memberships/invite |
| Withdraw an invitation | DELETE /tenants/{orgId}/user_memberships/invitations/{invitationId} |
| Get invitation details | GET /user_membership_invitations/{invitationId} |
| Accept an invitation | POST /user_membership_invitations/{invitationId} |