Account Membership
We've already explained that an account has an account holder.
When an account is opened for a physical person, it is often linked to just one person. But not necessarily. Take for example an account with guardianship ⇒ A grandma can give rights to her grandson to go buy her groceries. In this case, the account owner is grandma. Her grandson is just a user; he has an account membership.
An account membership represents the rights of a Swan user to use a given account. Every account is administered by a member that has legal representative status. The administrator can give multiple users rights to the account; each of these users would have an account membership.
The Swan user that initiated the onboarding of an account receives the first account membership and becomes legal representative.
When an account is opened for a legal person (such as a company or association), the legal representative will commonly delegate rights to the account to other members. Colleagues may receive an account membership if they often need to make payments autonomously, or a bookkeeper may receive an account membership in order to access the account statement.
A user can also access multiple accounts belonging to different account holders, like in the example below:

Account members can be assigned different rights to an account, restricting access to only the desired actions. These rights are referred to as permissions in the Swan API and frontend.
Swan doesn't offer role-base access control (RBAC); instead, you choose exactly what each account member can see and do on a member-by-member basis.
Permission | Account member can... |
---|---|
canViewAccount | View the account and information about the account, including:
|
canManageBeneficiaries | Add or remove beneficiaries |
canInitiatePayments | Initiate transfers to saved beneficiaries |
canManageAccountMembership | Add, modify, or remove account memberships |
canManageCards | Manage their own cards cards and cards for account memberships they manage |
Whether your account members can create cards and for whom depends on both
canManageAccountMembership
and canManageCards
permissions.canManage ... | AccountMembership = true | AccountMembership = false |
Cards = true | ✓ Create cards for self ✓ Create cards for others* | ✓ Create cards for self
☒ Can't create cards for others |
Cards = false | ☒ Can't create cards for self ☒ Can't create cards for others | ☒ Can't create cards for self
☒ Can't create cards for others |
Cards = optional | ✓ Create cards for self
✓ Create cards for others | ☒ Can't create cards for self
☒ Can't create cards for others |
*others → other account memberships
Only a pre-authorized member with the
canManageAccountMembership
right can invite new members to their account by using theaddAccountMembership
mutation. This very sensitive operation can be confirmed by Strong Customer Authentication through the user's smartphone.For each invitation, you must transmit the following information to Swan: the user's
email
, firstName
, lastName
, phoneNumber
, birthDate
(optional), and their rights.The
birthDate
field is obligatory when the account membership has these rights:canManageBeneficiaries
canInitiatePayments
canManageAccountMembership
CanManageCards
To secure access to the account, the new member's identity will be verified by Swan before they can perform sensitive operations. Learn More
For some use-cases we can remove the identity verification requirement on account membership. It will requires additional security on your side.
Please get in touch with [email protected] to learn more about this.

Overview of the process to add and bind an accountMembership
To invite a new member, there are two options:
- #nocode: you can use the interface to email the new member a URL invitation to the white-label bank.
- by API: you can integrate the new member into your system by using the
addAccountMembership
mutation. IfcanManageCards
is empty, it will inherit the value ofcanManageAccountMembership
.When you do this, make sure you are authentified with anaccessToken
using the identity of a member who has thecanManageAccountMembership
right. The new account membership is thus created with theConsentPending
status and aconsentUrl
is returned which invites the user to carry out Strong Customer Authentication with Swan. Learn More. Once the Strong Customer Authentication process is finished, the new account membership changes toInvitationSent
status. You will need to store the newaccountMembershipId
in order to bind a user to it.If the membership was added by API, we won't send an email to the new member, you will need to contact them and give them the procedure (see below) to create a user account. You must authenticate the new member using the protocol oauth2. Learn More.
When a Swan user responds to the invitation and connects for the first time, they will need to follow these steps:
- 1.Enters their phone number on the web page
- If onboarding via a mobile phone: a verification code will be sent to confirm the phone number
- If onboarding via a desktop: a link will be sent to confirm the phone number and open the verification process on the smartphone
- 2.On their smartphone enter some personal data like first name, last name and birthdate
- 3.Select a 6-digit passcode (and FaceID / TouchID, if applicable) that will be used every time we need to ask a consent to the user
- 4.Identity verification: a combination of identity documentation and biometric face recognition. This step can be performed later.
- 5.Start using Swan.
- nocode: if the invitation was sent through the white-label web banking, the user is redirected to the web banking.
- by API: if the invitation was sent through the API, the user is redirected to the oauth2 redirect URL which fetches the oauth2 authorization code and thereby obtains an
accessToken
. Using this token you need to call thebindAccountMembership
mutation with theaccountMembershipId
you stored after the call toaddAccountMembership
. This associates the account membership to the Swan user. Learn More.
A pre-existing user will only need to go through steps 3 to 5.
State diagram of an account membership status
For an account membership to be
Enabled
the user data must match the membership data and the user must be idverified=true
.When the account membership status is
Enabled
the user has access to all of their rights.If the data doesn't match, the user has
BindingUserError
status and one or more of the boolean fields below has true
status:mobilePhoneMatchError
firstNameMatchError
lastNameMatchError
birthDateMatchError
idVerifiedMatchError
When the account membership status is
BindingUserError
the user can access the account and their cards but cannot make any sensitive operations (such as make a transfer or consult their card numbers).When the account membership is
BindingUserError
, a member that is pre-authorized with the canManageAccountMembership
right to this account can update the account membership data (If a typo occurred when the invitation was sent out) or suspend the account membership (if fraud is suspected)It can happen that an account membership has no rights on the account, in which case:
canViewAccount=false
canManageBeneficiaries=false
canInitiatePayments=false
canManageAccountMembership=false
CanManageCards=false
This is the case when you want to give just one card to a user. In this case, the account membership is created straightaway with the
InvitationSent
status, without requiring consent from the account administrator. You can test this sequence as often as you'd like from your sandbox.
Using our API, the mutation AddAccountMemberships will add several members at once. If at least one of the members has one of the below rights, a strong customer authentication will be required:
canManageBeneficiaries
canInitiatePayments
canManageAccountMembership
canViewAccount
CanManageCards
When you do this, make sure you are authenticated with an
accessToken
using the identity of a member who has the canManageAccountMembership
right. The new account memberships are thus created with the ConsentPending
status and a consentUrl
is returned which invites the user to carry out Strong Customer Authentication with Swan. Learn More. Once the Strong Customer Authentication process is finished, the new account memberships change to InvitationSent
status. You will need to store all new accountMembershipId
in order to bind a user to them.As the memberships were added by API, we won't send an email to the new members, you will need to contact them and give them the procedure to create a user account. You must authenticate the new members using the protocol oauth2. Learn More. For the rest of the process, please refer to Single invitation as once created, all memberships will follow the process detailed for single invitations.
For performance reasons, bulk invitations are limited to 200 memberships per API call
Identity verification can be removed for some B2B cases only after making an agreement with our compliance. It is only possible to skip identity verification for users with an account membership. Here are the requirements:
canManageAccountMembership=false
canInitiatePayments=false
canManageBeneficiaries=false
canViewAccount=false or true
CanManageCards=false or true
To invite a member, you must use the API method and authenticate him by removing the
idverified
scope. Learn more.
If the Swan user connects for the first time, the idVerified
user's parameter remains at false
.
If ever the mobile phone doesn't match, the user status will be
BindingUserError
the field mobilePhoneMatchError
will say true
. When the account membership status is
BindingUserError
, that user can access their account and cards but cannot make any sensitive operations (such as consulting their card numbers).Modifying membership data: These very sensitive operations must be confirmed with consent.
A newly added account membership still in consent pending status cannot be updated. If the membership information is incorrect, it must be cancelled, and a new account membership should be created.
To perform this operation by API you must use the
updateAccountMembership
mutation. While doing this, make sure you are authenticated with an accessToken
using the name of the user behind the modification. Learn More. To modify, the user must have the canManageAccountMemberships
right. The users won't be able to give a permission they don't have themselves to another membership. Furthermore, the legal representative's accountMembership
can only be updated by themselves.The request from this mutation returns a newly created
consent
resource containing the consentUrl
. The url allows you to redirect the user making the modification to Swan's strong authentication. Learn more.Once the consent process is completed, the account membership is updated and its attribute
version
is increased by 1.Suspend or reactivate account memberships: These operations must be confirmed with consent.
To perform suspending operations by API you must use the
suspendAccountMembership
mutation while authenticated with an accessToken
using the name of the user behind the suspension. Learn More.Once suspended its attribute
version
is increased by 1.To perform reactivation operations by API you must use the
resumeAccountMembership
mutation while authenticated with an accessToken
using the name of the user behind the reactivation. Learn More.The request from this mutation returns a newly created
consent
resource containing a consentUrl
. The url redirects the user who requested to be reactivated to Swan's Strong Customer Authentication. Learn more.Once the consent process is completed, the account membership is reactivated and its attribute
version
is increased by 1.To disable an account membership, which will revoke the access to the account the user had, you must call the
disableAccountMembership
mutation. This mutation is non-sensitive and does not require consent. The accountMembership
will be moved to the Disabled
status.Disabling is referred to as permanently blocking on the Web Banking interface.
As soon as an account is closed, account members can no longer initiate payments or manage account memberships and beneficiaries.
Account members can still see the account for one year, after which all account memberships linked to the canceled account are disabled.
Last modified 4h ago