Skip to main content

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 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.

Sandbox users

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, as long as they're logging in with the same phone number.

Signing up​

Users sign up for Swan the first time their go through an authentication link. This typically occurs when they're invited to become an account member or during the onboarding process.

Your user:

  1. Opens their sign-up link.
  2. Enters their mobile number.
    • If you include their number when creating their sign-up link, they won't need to enter it again.
  3. Confirms their mobile number, after which they continue the sign-up process on their mobile device. How they confirm this step depends on whether they opened the sign-up link from a computer or their mobile device:
    • Computer: Swan sends your user a text message with a link to open on their mobile device.
    • Mobile device: Swan sends your user a text message with a verification code.
  4. Enters their personal information, including their name and birthdate. This information must match the information that appears on their identity documents.
    • If you include this information when creating their sign-up link, they won't need to enter it again.
  5. Selects a 6-digit passcode. They need to remember their passcode; Swan can request it anytime the user needs to consent to a sensitive operation.
  6. Completes identification, where Swan verifies their identity. This step can be performed later, though it's recommended to complete it as soon as possible. If you're using the API, you're responsible for triggering this step.
  7. Sets up biometrics, if desired and available on their mobile device. Biometrics typically include face or fingerprint authentication.

After signing up, your user can start using Swan.

  • If you're using Swan's provided Web Banking interface, Swan redirects your user to the interface automatically.
  • If you're using a custom API integration or a customization of Swan's 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.
End-user perspective of signing up for Swan

Logging in​

After signing up, logging into Swan is quick.

Your user re-enters their mobile number (every time, for security reasons), then either completes biometric authentication or enters the 6-digit passcode they chose when signing up.

Whether biometrics function correctly depends on your user's device. If your user configured biometrics and is logging in (or consenting to a sensitive operation) from that same device, biometrics should work as expected. However, if they access Swan from a new mobile device, they must enter their passcode. Then, if desired, they can configure biometrics on the new device.

Additionally, biometrics might be deactivated if Swan's API detects that the mobile device's operating system isn't up to date. In this case, the user enters their passcode to authenticate. Before trying to reconfigure biometrics, they need to update the software on their mobile device.

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:

  1. All the user's account memberships are disabled.
  2. The user isn't the legal representative for any account.
  3. 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 their associated refresh tokens associated with the deactivated user are revoked can no longer be used.

If conditions aren't met, there are three possible rejection reasons:

  1. UserCannotBeDeactivatedRejection: the explained conditions aren't met.
  2. UserAlreadyDeactivatedRejection: the user associated with this user ID was already deactivated.
  3. 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.

Webhook

To get a notification when a user is deactivated, subscribe to the User.Deactivated webhook.

Statuses​

StatusExplanation
ActiveUsers are Active as soon as they're created. They can access and use Swan.
BlockedStatus 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.
DeactivatedYou 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.
Access tokens

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.

Guides​