The Account Management API functions allow a user to perform both Account level and limited Tenant level administration tasks.
You will need an Account API Key to perform Account Management functions.
For more information on creating a Access Token, see:
The Account functions can be broken down into to levels:
Note: - The Tenant functions available to an Account are limited to Tenant creation / deletion and Tenant API Keys only.
For configuring Schemes, Apps, Reward Groups, and other Tenant objects, you must use a Tenant API Key.
All the Account Management API functions are fully documented in the Account API documentation.
The following models are used to define Accounts, Tenants, and API Keys.
{
"accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"imburseAccountRef": "string",
"companyName": "string",
"billingContactFirstName": "string",
"billingContactLastName": "string",
"billingContactAddress": {
"streetAddress": "string",
"extendedAddress": "string",
"locality": "string",
"region": "string",
"postCode": "string",
"country": "string"
},
"license": {
"licenseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"licenseName": "string",
"maxTenants": 0,
"maxTransactions": 0,
"maxCollectApps": 0,
"maxPayoutApps": 0
}
}
Property | Type | Mandatory | Description |
---|---|---|---|
accountId |
Guid | Yes | The Id for the Account. |
imburseAccountRef |
string | Yes | Your Imburse account reference. |
companyName |
string | Yes | Your organizations name. |
billingContactFirstName |
string | Yes | First name of your billing contact name. |
billingContactLastName |
string | Yes | Last name of your billing contact name. |
billingContactAddress |
Address model | Yes | Your organizations billing address. |
tenantCreationRequiresApproval |
boolean | Yes | When set to true , new tenants will have to go throughan approval process. Users with the role account-tenant-approval can see and approve or reject the new tenant. |
license |
License Model | n/a | Your organizations current license details. |
{
"streetAddress": "string",
"extendedStreetAddress": "string",
"locality": "string",
"region": "string",
"postCode": "string",
"country": "string",
}
Property | Type | Mandatory | Description |
---|---|---|---|
streetAddress |
string | Yes | Street address of your organization. |
extendedStreetAddress |
string | No | Extended / 2nd line of the street address of your organization. |
locality |
string | Yes | Town or City of your organizations address. |
region |
string | Yes | Region / Country / State of your organizations address. |
postCode |
string | Yes | Post Code / Zip Code of your organizations address. |
country |
string | Yes | The country of your organizations address. |
{
"licenseId": "string",
"licenseName": "string",
"maxTenants": 0,
"maxTransactions": 0,
"maxCollectApps": 0,
"maxPayoutApps": 0
}
Property | Type | Description |
---|---|---|
licenseId |
string | The license Id. |
licenseName |
string | The license name. |
maxTenants |
string | Max number of tenants for this license. |
maxTransactions |
string | Max number of transactions your license entitles you to. A value of -1 indicates unlimited. |
maxCollectApps |
string | Max number of apps allowing collections your license entitles you to. A value of -1 indicates unlimited. |
maxPayoutApps |
string | Max number of apps allowing payouts your license entitles you to. A value of -1 indicates unlimited. |
This model applies to both Account API Keys and Tenant API Keys.
{
"accountId": "string",
"tenantId": "string",
"name": "string",
"publicKey": "string",
"privateKey": "string",
"roles": [ "string" ]
}
Property | Type | Mandatory | Description |
---|---|---|---|
accountId |
string | Yes | The Id of the Account that owns the key. Only applicable to Account API Keys. |
tenantId |
string | No | The Id of the Tenant that owns the key. Only applicable to Tenant API Keys. |
name |
string | Yes | A friendly name for this Key. If no name is specified a default name of `API Key` will be set. |
publicKey |
string | Yes | The Public Key portion of the API Key. |
privateKey |
string | Yes | The Private Key portion of the API Key. The Private Key value cannot be retrieved after creation so it's important it is captured and stored somewhere safe. |
roles |
Array of strings | Yes | The roles given to this Key. These will be either Account Roles or Tenant Roles. |
{
"id": "string",
"accountId": "string",
"name": "string",
"address": {
"streetAddress": "string",
"extendedStreetAddress": "string",
"locality": "string",
"region": "string",
"postCode": "string",
"country": "string"
}
}
Property | Type | Mandatory | Description |
---|---|---|---|
id |
Guid | Yes | The Tenant Id. |
accountId |
Guid | Yes | The Id of the Account this Tenant is owned by. |
name |
string | Yes | The Tenant name. |
address |
Address model | Yes | The Tenants address. |
An Account has access to four main components:
The diagram below shows the relationship between these four components.
The Account is the root of the system. The Account API Keys and Tenants are child objects of the Account.
Your Account is set up by Imburse upon registration.
When your Account was initially set up you would have been issued with an Account API Key to allow you to access the APIs.
You can set up additional Account API Keys as you require.
Important - Creating an Account API Key will generate your Public Key and Private Key values. The Private Key value cannot be retrieved after creation so it's important it is captured and stored somewhere safe.
The capabilities of an Account API Key are dependent on the Account Roles that are assigned to it. The following table shows the Account Roles that are available:
Account Role Name | Description |
---|---|
account-admin |
Account Admin access to all aspects of an Account, including Users and API Keys. |
account-tenant-read |
Tenant Management read access |
account-tenant-write |
Tenant Management read + write access |
account-tenant-approval |
Users can approve new Tenant requests. See Tenant Approvals below for more information. |
An Account API Key can have multiple roles assigned to provide the required access.
When adding an API Key, the response from the API will contain the new Private Key value. This Private Key will only be issued once and should be stored securely.
When choosing the roles to apply to an API Key, only select the minimum to satisfy the requirements of the intended purpose.
Deleting a Key will immediately revoke access to ALL APIs.
This action cannot be undone.
You can consider a Tenant as either a company, department, or organization.
You can add as many Tenants to your Account as you require.
A Tenant cannot be deleted once created.
If you would like to approve new tenants before they are used then you can set the tenantCreationRequiresApproval
property to true
on the Account.
You will also need to make sure you have at least one user that has the role account-tenant-approval
.
Users with this role will be notified to their user email address that a new tenant request is awaiting approval.
Any user in this role can then log into the Client Portal and see the list of tenants awaiting approval.
A tenant that is awaiting approval can be either approved or rejected.
A Tenant can have as many Tenant API Keys as you require.
Important - Creating a Tenant API Key will generate you Public Key and Private Key values. The Private Key value cannot be retrieved after creation so it's important it is captured and stored somewhere safe.
The following Tenant Roles are available:
Tenant Role Name | Description |
---|---|
tenant-admin |
Tenant Admin - Read + write access to all aspects of a Tenant, including Users and API Keys. |
tenant-management |
Tenant Information access |
tenant-app-read |
Apps read access |
tenant-app-write |
Apps read + write access |
tenant-collect-scheme-read |
Collect Schemes read access |
tenant-collect-scheme-write |
Collect Schemes read + write access |
tenant-payout-scheme-read |
Payout Schemes read access |
tenant-payout-scheme-write |
Payout Schemes read + write access |
tenant-reward-group-read |
Reward Groups read access |
tenant-reward-group-write |
Reward Groups write access |
tenant-transaction-read |
Transactions read access |
tenant-transaction-write |
Transactions read + write access |
A Tenant API Key can have multiple roles assigned to it as are deemed necessary for the capabilities your require.
When adding an API Key, the response from the API will contain the new Private Key value. This Private Key will only be issued once and should be stored securely.
When choosing the roles to apply to an API Key, only select the minimum to satisfy the requirements of the API Keys intended purpose.
Deleting a Key will immediately revoke access to ALL APIs.
This action cannot be undone.
As the Account holder, you can control the creation of Tenant API Keys and the permissions they have.
Depending upon the nature of your business, you may want to restrict what your Tenants can do by only creating Tenant API Keys with limited functionality; including restricting a Tenant from creating their own keys.
Conversely, you could also create just one Tenant API Key that has permissions to create further Tenant API Keys; in effect making the Tenant fully independent from the Account holder and able to self provision within the Tenant.