Client and Group Roles Configuration
  • 11 Jan 2023
  • 5 Minutes To Read
  • Dark
    Light
  • PDF

Client and Group Roles Configuration

  • Dark
    Light
  • PDF

Early Access Feature
If you would like to request early access to this feature, please get in touch with your Mambu Customer Success Manager to discuss your requirements. For more information, see Mambu Release Cycle - Feature Release Status.

A client models any customer that is just an individual. A group models any customer that is not an individual.

You can specify particular client roles and group roles, which are also referred to as client types and group types. For more information, see Clients and Groups Overview.

With Configuration as Code (CasC), you may batch configure your client and group role configuration via the API using YAML. For general information on CasC, see Configuration as Code Overview.

Please Note

Although the path for this API is /configuration/clientroles.yaml, it is used for both client roles and group roles.

Please be Aware

Do not confuse group roles in this article with the group roles names that can be assigned to members of a group, found in the Mambu UI under Administration > General Setup > Group Roles.

API Operations

CasC for client roles and group roles supports two operations.

Action Endpoint Description
GET /configuration/clientroles.yaml Get current client roles and group roles configuration.
PUT /configuration/clientroles.yaml Write a new client roles and group roles configuration to Mambu.

Parameters

To retrieve only client roles or only group roles when making a GET request, you may provide the type parameter with the value CLIENT or GROUP.

The type parameter is not supported for PUT requests. The API determines whether updates affect clients or groups automatically, based on the contents of the rolesConfiguration in the configuration.

Note that this has implications for how roles are deleted - for more information, see Deleting client or group roles below.

Managing configuration files

You may manage YAML configuration files in two ways: either include client roles and group roles in a single file, or store them separately in two files, one for group roles and one for client roles.

Requests

For general information on CasC requests such as authentication and required headers, see Configuration as Code Overview.

The following section shows sample requests using curl and basic authentication. For all examples, replace TENANT_NAME with your actual tenant name.

GET configuration

curl -X GET 'https://TENANT_NAME.mambu.com/api/configuration/clientroles.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Authorization: Basic {auth}'

{auth} is the base-64-encoded value of username:password. For more information, see Authentication in our API reference.

PUT configuration

curl -X PUT 'https://TENANT_NAME.mambu.com/api/configuration/clientroles.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Content-Type: application/yaml' \
-H 'Authorization: Basic {auth}' \
--data-binary @clientroles.yaml

{auth} is the base-64-encoded value of username:password. For more information, see Authentication in our API reference.

@clientroles.yaml represents the absolute path of the file on your device.

Use “--data-raw” if you want to specify the YAML body inline.

Configuration body example

rolesConfiguration:
  - type: "CLIENT"
    defaultRole:
      id: "default_role_id"
      name: "default_role_name"
      canOpenAccounts: true
      canGuarantee: true
      requireIdentificationDocuments: false
      useDefaultAddress: true
    roles:
      - id: "id_1"
        name: "Name_1"
        description: "Desc 1"
        idPattern: "@"
        canOpenAccounts: false
        canGuarantee: false
        requireIdentificationDocuments: false
        useDefaultAddress: false
  - type: "GROUP"
    defaultRole:
      id: "default_group_role_id"
      name: "default_group_role_name"
      canOpenAccounts: true
      canGuarantee: true
      useDefaultAddress: true
    roles:
      - id: "id_2"
        name: "Name_2"
        description: "Desc 2"
        idPattern: "##"
        canOpenAccounts: false
        canGuarantee: true
        useDefaultAddress: true
      - id: "id_3"
        name: "Name_3"
        description: "Desc 3"
        idPattern: "@#"
        canOpenAccounts: true
        canGuarantee: true
        useDefaultAddress: false

rolesConfiguration attributes

Name Type Description Required
rolesConfiguration List List of all roles for available account holder types.
type String Defines the role type, it can either be CLIENT or GROUP.
defaultRole List The default role for the given type.
roles List A list of roles for the given type, except the default role.

roles attributes

Name Type Description Required
id String The ID used to identify an existing role in the system. If the ID doesn't match an existing role, a new role will be created.
name String The name of the client or group role.
description String The description for the role
idPattern String The ID pattern for the client or group role.
canOpenAccounts Boolean Indicates whether new accounts for this client type can be created.
canGuarantee Boolean Indicates whether the clients under this type can be used as guarantors.
useDefaultAddress Boolean Indicates whether the default address section will be available.
requireIdentificationDocuments Boolean Indicates whether identification documents must be provided for the client to be created. Does not apply for groups.

Deleting client or group roles

When updating client or group roles, any existing client or group role that you do not include in the new configuration will be deleted. Note that you may not delete any client or group role that is currently in use.

Because this endpoint is used to configure both client and group roles, if you entirely omit either role type, then the type you leave out will not be affected. That is, you may update only client roles or only group roles configuration without deleting the other type.

For example, if you update rolesConfiguration with the type CLIENT only, then any existing client roles not included in the new configuration will be deleted, but your group roles will not be affected, and no group roles will be deleted.

Replies

If you do not receive a 200 OK response then fix any validation errors and make another PUT request until you receive a 200 OK response.

Please Note

If you PUT a valid YAML configuration to the API and you do not receive a 200 OK status code within 60 seconds, you may receive a 504 Gateway Timeout status code. We expect all responses to be below 60 seconds.

If you encounter this issue, please contact us through Mambu Support so we can investigate it.

Validations

rolesConfiguration

Name Validation
rolesConfiguration Doesn't accept empty or null elements in the list.
type It can appear only once in the file, all the roles for either CLIENT or GROUP must be defined under the respective configuration.
defaultRole The ID can not be changed.
roles Doesn't accept empty or null elements in the list. It can be empty if there are no roles except for the default role.

roles

Name Description
id It is unique per role type. Maximum of 32 characters.
name It is unique per role. Maximum of 255 characters.
description Maximum of 256 characters.
idPattern It can contain only alphanumeric characters, '#' numbers, '@' for letters or '$' for letters or numbers. Maximum of 32 characters.
requireIdentificationDocuments It can only be defined for roles with type CLIENT.

Warnings

If you make an API call and we detect something we need to warn you about then you will receive a list of warnings with a descriptive message for each.

For example, if you attempt to delete a client role that is in use then you will receive the error message ClientRole [CLIENT, id_0] could not be deleted: Client role in use.


Was this article helpful?