Organizations using the Arcoro public API can already create people and employee records, but that workflow stops short of granting login access. Even when an integration provides a username, no identity account is created automatically, which leaves administrators with a partially onboarded employee who still cannot sign in.

This gap is especially painful for users that rely on high-volume, API-driven onboarding. Instead of completing setup in one automated flow, they must pause and finish account activation manually in Hub or through support-assisted follow-up. That adds delay, creates avoidable support tickets, and makes the API feel incomplete for user provisioning use cases.

This feature closes that gap by adding a dedicated user-management surface to the public API so users can create login access, send invitations, reset passwords, manage activation, enforce MFA, and maintain SSO identity mapping using Person-based endpoints.

• Complete onboarding faster — Users can create a person, employee record, and login access in one API-driven workflow instead of stitching together manual follow-up steps.
• Reduce administrative work — IT and HR teams can automate invitations, password resets, activation changes, and MFA resets without needing to intervene in Hub for routine account maintenance.
• Improve access reliability — The feature removes a common failure point where an employee exists in Arcoro but cannot log in because no user account was provisioned.
• Support secure identity management — Password setup remains email-token based, MFA can be enforced, and internal identity-linkage fields stay hidden from user-facing APIs.
• Work better with SSO environments — SSO-enabled users can manage external login usernames at the Person level so federated access can be included in onboarding and maintenance workflows.

Enhancements

This feature adds a new Person-centered user management API that lets users provision and maintain Arcoro login access without exposing internal identity service concepts.

How Users Access the Feature

Users use new endpoints under [/api/v{version}/UserManagement]. These endpoints work with [PersonId] only, so users do not need to know or manage internal Arcoro identity IDs. Users can also include an optional [UserAccess] block when creating a Person through [POST /Common/Persons] to provision access as part of the same transaction.

Core Capabilities

1. One-step access provisioning: Users can create a Person and user access in the same API call by including a [UserAccess] block with username, invitation behavior, MFA requirement, and initial active state.
2. Invite existing people to Arcoro: Users can provision login access for an existing Person who does not yet have an account by calling the dedicated Invite endpoint.
3. Manage invitations and password resets: Users can resend invitations and trigger password reset emails through the API, allowing routine access recovery to be automated.
4. Control account state: Users can activate or deactivate accounts after creation and can enforce MFA or reset authenticator-based MFA enrollment as needed.
5. Read and search access status: Users can retrieve user access details for a specific Person and list users by filters such as email, active status, MFA-required status, and login state.
6. Support SSO identity mapping: For users with SSO enabled, the external login username can be managed on the Person record and surfaced in the user access view.

Interactions with Existing Arcoro API behavior

This feature preserves existing Person-create behavior when no [UserAccess] block is provided. It also removes the older implicit behavior where certain Person updates could create identity access as a side effect. Going forward, login provisioning happens only through the new explicit invite flow or the inline access block during Person creation. Email and phone updates remain owned by the existing Person endpoints and continue to sync to the linked identity account.

Data and Access Guidelines

1. Person-based addressing only: All user-facing user management operations use [PersonId]. Internal identity identifiers are not exposed in routes, request bodies, or responses.
2. Passwords are never set directly: Users can trigger password reset emails, but they cannot set passwords through the public API. This preserves the existing secure email-token flow.
3. Email and phone remain Person-owned: Users continue to update those values through the Person endpoints, not through dedicated user-management email or phone endpoints.
4. SSO writes are conditional: [ExternalLoginUsername] can only be written when the user company has SSO enabled. Otherwise, the API rejects the write.
5. Internal linkage fields stay protected: Fields such as [IdentityUserUnique] are removed from the writable user surface and are not returned in responses.
6. Tenant isolation is enforced: Requests are resolved within the caller's tenant context, and cross-tenant Person references return not found rather than exposing account existence.

Availability and Access

This feature is available to users using the Arcoro public API who have the necessary API permissions to manage people and user access.

• Integration users with permission to create or edit Person records and manage user access.
• User administrators and IT teams automating account provisioning, invitations, password resets, MFA controls, or SSO identity mapping.

Users will not be able to use all actions unless their API credentials include the required permissions. SSO-specific capabilities are only available for companies with SSO enabled.

FAQs

Can users create a login at the same time they create a Person?

Yes. Users can include an optional UserAccess block in POST /Common/Persons to create the Person, provision login access, and optionally send the invitation in the same transaction.

Can users set a user's password directly through the API?

No. For security reasons, the public API does not support direct password setting. Users can trigger the standard admin-initiated password reset email instead.

What happens if access provisioning fails during Person creation?

The operation rolls back so users do not end up with a partially created onboarding state where the Person exists but the user account does not.

How do users manage email and phone changes for users?

They continue to update email and phone through the existing Person endpoints. The linked identity account is expected to stay in sync automatically.

Can SSO users manage external login usernames through this work?

Yes. When SSO is enabled for the user's company, ExternalLoginUsername can be written on the Person record and is surfaced in the related user access view.

Will every user be able to use the new user-management actions?

Only users with the required API permissions will be able to use the new endpoints. Some actions, such as SSO mapping, also depend on user-specific configuration.