Tenant onboarding

The tenant API lets you create and administer tenants efficiently. This documentation shows you how to create a tenant and a corresponding icon.

For more documentation on the tenant API, open API reference / Tenant management in new tab.

Step 1 – create a tenant

When you create a tenant, it’s automatically added to the client scope. The client needs to re-authenticate for the new scope to take effect.

Note: Creation of tenants via API is only allowed in certain specific cases and its usage needs to be regulated in the business relationship between the sender party and Kivra.

The following details are required to create a tenant:


The name of the Tenant. This name shows up in the recipient’s inbox.



The legal name of the company, i.e. the name that is registered with Bolagsverket (Swedish Companies Registration Office). This may or may not be the same name as the name of the tenant (above). For example, a tenant might have “Darth Vader” as its public-facing brand name, and “Darth Vader AB” as its legal name.


VAT number of the company.

Step 2 – provide an icon for a tenant

Add or update the tenant icon. If an icon already exists, it will be changed.

To check the current icon associated with a tenant you can simply go to the following addresses:

The icon needs to be in the following format:

  • Dimensions: squared icon with a size between 256x256 px and 512x512 px
  • Alpha Channel: 32-bits
  • Format: PNG
  • File size: up to 1MB

Note! For the best user experience, we recommend leaving a little white space around the logo.

The following details are required (or, where stated, optional) for tenant icons:


The unique key for a tenant.


The file containing the icon


Optional filename.


Base64-encoded data. Max size is 134 kB when encoded, which is roughly equivalent to 100 kB before encoding. The image format must be PNG. The image must be quadratic (that is, width and height must be the same). The sides must be at least 256 pixels long, and at most 512 pixels long. The image must have an alpha channel.


The IANA media type corresponding to the file, e.g. "image/png"

For more endpoints and information on the tenant API, open API reference / Tenant management in new tab.

Got feedback? We'd love to hear it!