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.

How to list all users for my mandator

Users may be listed using the GET /v1/users endpoint with client (mandator) credentials, using a Bearer token obtained with the client_credentials claim via the /oauth/access_token endpoint.

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 mandator's public ID (like “rentablo”).

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

Managing your users

We provide a dedicated role ROLE_MANDATOR_CREDENTIALS allowing you to manage your user base via client credentials (oAuth claim client_credentials).

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 user's mandator, using mandator credentials. Alternatively, a user with role ROLE_USER_MANAGEMENT may reset a user's 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 do so, a user account in your organization must have ROLE_USER_MANAGEMENT. This account may then update the user with a new password using the update user endpoint. Again, an update can only be done via specifying the user's email / username.

Resetting via mandator credentials

It is possible to reset user-passwords with mandator credentials. For security reasons, this is only allowed by providing the username you assigned during signup process as part of the URL. A request submitted with valid mandator credentials will be able to update the user with a new password using 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 user's 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

Token validity and revocation

We use JWT; refresh token validity is configurable.

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 for a given user, use the endpoint DELETE /oauth/revoke_token.

A note on two-factor authentication via TOTP

Our oAuth API supports grant type two_factor_authentication. This is however intended exclusively for business cases, where the user authentication happens solely against our API; i.e. users are not managed by a third-party-layer.

As a wealthAPI partner, you will typically

create users programmatically
obtain access tokens using user AND client credentials
perform administrative tasks using mandator (client) credentials
you will however NOT user our 2FA routines to allow your users to log in

Handling wealthAPI user passwords