Users overview
A Swan user is an actual person identified within Swan by their mobile phone number. Swan users are managed globally, not project-by-project. Therefore, users can log into multiple projects with the same phone number.
Authentication
When a user wants to access their data or make transactions through your service with Swan's API, they must be authenticated. This includes when they log into their Web Banking app, whether it's Swan's open source version or your own custom integration.
Phone numbers
Using mobile phone numbers to identify users greatly simplifies their experience: users only need to know their mobile number to log into Swan, and occasionally their chosen 6-digit passcode. Their passcode is linked to their mobile phone number and is the same for all projects in both the Sandbox and Live environments.
Note that if your users get a new phone number, they should change their number with Swan. They can update their phone number independently by tapping New phone number? Update it at the start of any login or consent flow, then follow the prompts. Users shouldn't sign up again with a new link, which would create a new Swan user.
If a user's mobile phone number previously belonged to someone else, and the number's former owner had a Swan account, that user must be deactivated before the new user can sign up with the phone number.
When testing your integration, you'll need Sandbox users. Sandbox users make it possible to simulate the different situations you may encounter with your real users in your Live environment. Sandbox and Live users share the same phone number.
Signing up
Users sign up for Swan the first time they go through an authentication link. This typically occurs when they're invited to become an account member or during the account onboarding process.
Your user:
- Opens their sign-up link.
- Enters their phone number.
- If you include their number when creating their sign-up link, they won't need to enter it again.
- Confirms their phone number. How they confirm depends on whether they opened the sign-up link from a computer or their mobile device:
- Desktop: Swan sends your user a text message with a verification code. The user enters this code on their computer to confirm their phone number.
- Mobile device: Swan sends your user a text message with a verification code.
- Enters their personal information: first name, last name, and birthdate. This information must match the information that appears on their identity document.
- The user skips this step if you included this information when creating their sign-up link.
- Sets a 6-digit passcode. Users must remember their passcode. Swan can request it anytime the user needs to consent to a sensitive operation.
- Completes email verification if included in the OAuth URL.
- This step only appears if email verification was configured in the sign-up link.
- If a user isn't required to complete identification, they can access Swan after setting their passcode.
- If a user is required to complete identification, they continue with steps 7-12.
- Enters their birth information: birth city, postal code, country, and nationality.
- If you include this information when creating their sign-up link, they won't need to enter it again.
- Enters their residency information. Swan only requests the information required for the relevant identification process (to be completed in step 9).
QESprocess: residency address, city, country, and postal code.PVIDorExpertprocess: residency country only.- If you include this information when creating their sign-up link, they won't need to enter it again.
- Reviews and confirms all provided information: personal, birth, and residency. Users can modify their information before confirming.
- Completes identification, where Swan verifies their identity. This step can be performed later, though it's recommended to complete it as soon as possible. When using the API, you must trigger this step.
- (Optional) Sets up biometrics, if desired and available on their mobile device. Biometrics typically include face or fingerprint authentication.
- Gets redirected to your redirect URL.
If a user's identification fails, they receive a text message after completing sign-up with the reason for the failure. They must follow the link provided to retry.
Share the support article on Identification rejection reasons and solutions to help your users troubleshoot the identification process.
Sign-up diagram
The following diagram illustrates the steps to sign up for Swan.
End-user perspective of signing up
Accessing accounts
After signing up, your user can start using Swan. How they get to their account depends on your integration:
| Integration | Access |
|---|---|
| No-code Web Banking | Swan redirects your user to the interface automatically. |
| Full API or Customized open source frontend | Your user is redirected to the redirectUrl you supplied when creating their sign-up link. Make sure to declare your redirectUrl on your Dashboard > Developers > Redirect URIs. Otherwise, the redirection fails. |
Logging in
After signing up, logging into Swan is quick.
Your user re-enters their mobile number (every time, for security reasons), then authenticates. How authentication works depends on the device:
- Desktop: Swan sends your user a text message with a verification code. The user enters this code on their computer, then enters the 6-digit passcode they chose when signing up.
- Mobile: Swan sends your user a text message with a verification code. The user enters this code, then either completes biometric authentication or enters their 6-digit passcode.
Biometrics are only available on mobile devices. If your user accesses Swan from a new mobile device, they must enter their passcode. They can then configure biometrics on the new device if desired.
End-user perspective of logging into Swan
End-user perspective of resetting their passcode
User deactivation
In certain circumstances, you might want to deactivate a user. When a user is deactivated successfully, the phone number associated with their Swan user object can be used for a new user.
All of the following conditions must be met:
- All the user's account memberships are disabled.
- The user isn't the legal representative for any account.
- The user doesn't have a team membership to any of your projects.
- Go to Dashboard > your profile > Team management to confirm the user isn't a team member.
If all conditions are met, the user can be deactivated. When a user is deactivated, all user access tokens and refresh tokens associated with the deactivated user are revoked and can no longer be used.
If conditions aren't met, there are three possible rejection reasons:
UserCannotBeDeactivatedRejection: the explained conditions aren't met.UserAlreadyDeactivatedRejection: the user associated with this user ID was already deactivated.UserNotFoundRejection: the user associated with this user ID wasn't found in the system.
Learn how to deactivate a user with the API. You can also submit a request to Swan Support.
To get a notification when a user is deactivated, subscribe to the User.Deactivated webhook.
Statuses
| Status | Explanation |
|---|---|
Active | Users are Active as soon as they're created. They can access and use Swan. |
Blocked | Status assigned by Swan for security reasons.Blocked users can't access or use Swan services. The phone number remains attached to the user and can't be used for someone else. In certain edge cases, Blocked users can return to Active after careful review. |
Deactivated | You can deactivate users with the API, and Swan can also assign this status. Deactivated users can't access Swan or use Swan services. Phone numbers attached to Deactivated users can be assigned to someone else. |
User access tokens associated with Blocked or Deactivated users are revoked as soon as the status changes from Active.
You can no longer use the API on their behalf.
You also can't use a project access token to impersonate Blocked or Deactivated users.