Create a User

An administrator can create users in Authway admin UI and we always recommend to evaluate if auto-provisioning is possible since that remove a lot of manual (and double) administration. There are also valid reasons to use our admin APIs to create users.

A user in Authway is actually two objects, a person object and a user object. A person can exists without a user, but a user always requires a person. Both objects exists in a tenant and a person can be assigned to a subsidary if needed. There are scenarios where only a person should be created, but focus will be on users in this document.

Since the person/user is bound to a specific tenant all API calls to them is required to include tenant information as explained in the Introduction to admin APIs.

API:s to create a person and a user

Since a user requires a person, the normal way of creating a user is through the POST Person API. In the post it is possible to pass parameters so that both the person and the user is created in a single call. It is not possible to set password or other credentials for a user, but instead a user should be invited (or auto-linking can be used).

Please don’t pass the Id (it is not required) if not absolutely necessary as explained in the “Introduction to admin APIs”.

Invite a user

When creating a user through the POST Person API, there are a flag that can be set if you want Authway to send an invitation to the user. When setting the flag to true, it is also possible to pass additional parameters that should be added to the invitation link. Additional parameters:

  • clientId=[a client id]: The value of a registered application (client). When this parameter is passed the pages will use custom styles if that is registered for the client. The user will also be returned to URL registered on the client, when the account creation is completed.
  • link=true: Triggers the flow where a invited user will have to sign-in or create a personal account that the organisation account will be linked to. Read more about linking of users.

It is also possible to get an invitation link through the API if you want to share the link through other mechanisms or if more control over the e-mail creation is needed.

An invitation link is valid for 24 hours by default, but this can be configured in your instance.

Events during creation of person and user

There will be multiple events during the process of creating a user.

During the API calls to POST Person:

When the user uses the invitation link and completes the registration:

If a clientId parameter is included in the invitation link, the events will have metadata about the client (ClientId and ClientName); otherwise not.

Assign groups to a user

Normally it is also required to assign groups to the user so that the user will have permissions to do anything in the applications. Groups are assigned through the Group API. When adding groups it is possible to pass group id:s or group names, but it is not allowed to send a mix of both.

Subsections of Create a User

Link Users

Read about linked users so that you understand the concept and its limitations before continuing on this more developer focused documentation.

Create linked users

By invitation

Add query string parameter link=true to the invitation link will trigger a flow where the user must sign-in with (or create) a personal account which will do the linking automatically.

By API calls

To create users that should be linked you do the same as for a regular user. After the user is created, it is possible to link the user to a parent by POST users/{newly created user id}/link/{parent user id}.

Events during linking

A UserClaimAdded event is raised when a user is linked to a parent user. The event is raised to the child user (the same user that the link API was used for), which means that the AggregateId will have the value of the child user. The ClaimType will be “sub” and the ClaimValue will have the unique identifier of the parent user.