Handling wealthAPI user passwords

Securely creating users for server-to-server use cases

Users are created via the /v1/signup endpoint. A user will receive an email (= username) and a password by the creating service. For server-to-server use cases, we strongly recommend to use a random hash as email / username instead of a real email address. This will greatly improve security against email dictionary attacks.

When creating the user, your mandator secret is required.

Listing your users

You may list your users using the GET /v1/users endpoint in combination with your mandator credentials.

When is a user password assigned

A user password is assigned (by you) when you first signup a user. Note that a server-to-server signup process must provide the clientSecret in order to skip the otherwise mandatory email verification.

How to authenticate a user

User authentication is done either via username and password or via refresh token. Use the /oauth/access_token endpoint with the respective scope to either login-in or exchange a refresh token for an access token.

Note that both, login and token exchange will require your mandator credentials as a second authentication factor, as specified by the oauth standard - see our API documentation for details.

The login request including client credentials will then look as shown below. Please not the the client_id should be a hash and not your mandators public ID (like “rentablo”).

{
  "grant_type": "password",
  "client_id": "aabbccddeeffgghhiijjkkllmmoo",
  "client_secret": "bbccddeeffgghhiijjkkllmmoopp",
  "username": "the-username",
  "password": "the-password"
}

How to change a user’s password

A user may change his password using the current password via the changePassword operation:
https://sandbox.wealthapi.eu/apiDocumentation/swagger#/users/changePassword

This option may only be executed if the user is a) logged-in and b) knows his password.

How to reset a user password

A password can be reset by the users mandator, using mandator credentials. Alternatively, a user with role ROLE_USER_MANAGEMENT may reset a users password. In any case, resetting passwords is limited to users in the scope of the authenticated mandator.

For security reasons, editing users (including resetting the password) with mandator credentials is only possible by specifying the username / email. Note that in the case of server-to-server-users the email / username will typically be a random hash assigned by the creating service.

Resetting via `ROLE_USER_MANAGEMENT`

To so so, a user account in your organization must have ROLE_USER_MANAGEMENT. This account may then update the user with a new password user the update user endpoint. Again, an update can only be done via specifying the users email / username.

Resetting via mandator credentials

In order to reset a users password, via mandator credentials, you must provide the clientId and clientSecret in the request header using the following header parameters:

X-Mandator-Client-Id
X-Mandator-Client-Secret

A request submitted with valid mandator credentials will be able to update the user with a new password user the update user endpoint.

Should I store user passwords?

When storing user credentials, these must always be stored encrypted. Due to the oauth implementation we consider encrypted storage of user credentials as secure.

An alternative to storing user credentials is to just store the refresh token. The refresh token may then be used to acquire a new user token once it expires. Note that the refresh token may also expire based on your mandator settings.

In case you did not store the user credentials and your refresh token expired, you must reset the users password. The process would then be

reset user password using mandator credentials
obtain a new token and refresh token using user credentials
store the new refresh token

Validity of token and refresh_token

The token is valid for 60 minutes.

The refresh_token has by default no restriction on token lifetime. A custom token validity period may be configured on mandator level.

Revoking refresh tokens

We use JWT which is a stateless token by design. The easiest way to revoke a JWT is by deleting it.

For added security, we provide a way to revoke all valid refresh tokens for a certain user. To revoke all valid refresh tokens, use the endpoint