Client and Group Roles Configuration
  • 03 May 2023
  • 5 Minutes To Read
  • Dark
    Light
  • PDF

Client and Group Roles Configuration

  • Dark
    Light
  • PDF

Article summary

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.

ActionEndpointDescription
GET/configuration/clientroles.yamlGet current client roles and group roles configuration.
PUT/configuration/clientroles.yamlWrite 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

NameTypeDescriptionRequired
rolesConfigurationListList of all roles for available account holder types.
typeStringDefines the role type, it can either be CLIENT or GROUP.
defaultRoleListThe default role for the given type.
rolesListA list of roles for the given type, except the default role.

roles attributes

NameTypeDescriptionRequired
idStringThe 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.
nameStringThe name of the client or group role.
descriptionStringThe description for the role
idPatternStringThe ID pattern for the client or group role.
canOpenAccountsBooleanIndicates whether new accounts for this client type can be created.
canGuaranteeBooleanIndicates whether the clients under this type can be used as guarantors.
useDefaultAddressBooleanIndicates whether the default address section will be available.
requireIdentificationDocumentsBooleanIndicates 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 status code then fix any validation errors and make another PUT request until you receive a 200 OK status code.

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

NameValidation
rolesConfigurationDoesn't accept empty or null elements in the list.
typeIt can appear only once in the file, all the roles for either CLIENT or GROUP must be defined under the respective configuration.
defaultRoleThe ID can not be changed.
rolesDoesn't accept empty or null elements in the list. It can be empty if there are no roles except for the default role.

roles

NameDescription
idIt is unique per role type. Maximum of 32 characters.
nameIt is unique per role. Maximum of 255 characters.
descriptionMaximum of 256 characters.
idPatternIt can contain only alphanumeric characters, '#' numbers, '@' for letters or '$' for letters or numbers. Maximum of 32 characters.
requireIdentificationDocumentsIt 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?