Account Management

The Account Management API functions allow a user to perform both Account level and limited Tenant level administration tasks.

Access Requirements

You will need an Account API Key to perform Account Management functions.

For more information on creating a Access Token, see:

• Getting Started - Authentication
• Tutorials - Get a Access Token

Functions

The Account functions can be broken down into to levels:

• Account level functions
• Tenant level functions

The Account level functions available are:

• Get Account details
• Create new Keys
• Get a list of all Keys
• Get a key by its Public Key value
• Update a Key
• Delete a Key
• Get License History

The Tenant functions available from your Account are:

• Create new Tenants
• Get a list of all Tenants
• Get a Tenant by its Id
• Update a Tenant
• Delete a Tenant
• Create new Tenant API Keys
• Get a list of all Tenant API Keys
• Get a Tenant API Key by its Public Key value
• Update a Tenant API Key
• Delete a Tenant API Key

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.

API Documentation

All the Account Management API functions are fully documented in the Account API documentation.

Models

The following models are used to define Accounts, Tenants, and API Keys.

Account Model

{
  "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
  }
}

Address Model

{
    "streetAddress": "string",
    "extendedStreetAddress": "string",
    "locality": "string",
    "region": "string",
    "postCode": "string",
    "country": "string",
}

License Model

{
	"licenseId": "string",
	"licenseName": "string",
	"maxTenants": 0,
	"maxTransactions": 0,
	"maxCollectApps": 0,
	"maxPayoutApps": 0
}

API Key Model

This model applies to both Account API Keys and Tenant API Keys.

{
	"accountId": "string",
	"tenantId": "string",
	"name": "string",
	"publicKey": "string",
	"privateKey": "string",
	"roles": [ "string" ]
}

Tenant Model

{
	"id": "string",
	"accountId": "string",
	"name": "string",
	"address": {
		"streetAddress": "string",
		"extendedStreetAddress": "string",
		"locality": "string",
		"region": "string",
		"postCode": "string",
		"country": "string"
	}
}

Account Setup

An Account has access to four main components:

• Account
• Account API Keys
• Tenants
• Tenant API Keys

The diagram below shows the relationship between these four components.

Account

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.

Account API Keys

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.

Account Roles

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:

An Account API Key can have multiple roles assigned to provide the required access.

Adding an Account API Key

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 an Account API Key

Deleting a Key will immediately revoke access to ALL APIs.

This action cannot be undone.

Tenants

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.

Tenant Approvals

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.

Tenant API Keys

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.

Tenant Roles

The following Tenant Roles are available:

A Tenant API Key can have multiple roles assigned to it as are deemed necessary for the capabilities your require.

Adding a Tenant API Key

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 Tenant API Key

Deleting a Key will immediately revoke access to ALL APIs.

This action cannot be undone.

Key Management Strategy

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.