Tenant Management

A tenant is the sender identity used by the Tenant API. Its name and icon help the recipient recognise who sent the content, and its tenantKey appears in tenant-specific API paths.

The client is the OAuth identity making the request. A client may act directly as its own tenant or act as a partner sending on behalf of another tenant.

The tenant name is the public-facing sender name shown in the recipient inbox. It can differ from the legal company name. The legal company identifier must use the registered company name and Swedish VAT number.

In this page, a company identity is the legal entity represented by a sender tenant. This is different from a company recipient, where the company receives content in its Kivra Business inbox.

Use this feature only for delegated sending

Tenant management is intended only for clients that send content on behalf of another tenant, such as a platform or service provider onboarding and supporting its customers. If your organisation sends its own content, use the tenant provisioned during onboarding instead. Do not create or request access to tenants unless this delegated-sending use case has been agreed with Kivra.

Management workflow

Use the management endpoints to find or establish the sender tenant before sending content:

Goal	Method and endpoint	Notes
List accessible tenants	GET /v2/tenant	Optionally filter by orgnr.
Create or add a tenant	POST /v2/tenant	The tenant is added to the client scope.
Read tenant details	GET /v2/tenant/{tenantKey}	Use the returned key in content requests.
Update the sender name	PUT /v2/tenant/{tenantKey}/name	The new name appears to end users after new content is delivered.
Add a company identity	POST /v2/tenant/{tenantKey}/company_id	A tenant can represent one or more company identities.
Remove a company identity	DELETE /v2/tenant/{tenantKey}/company_id/{orgNr}	Supply the VAT number in orgNr.
Add or replace the icon	POST /v2/tenant/{tenantKey}/icon	Upload the icon as Base64-encoded PNG data.

All endpoints require the OAuth 2.0 client credentials described in Authentication. The token must include the operation’s required OAuth scope.

Create a tenant

Tenant creation by API is enabled only for agreed use cases. When allowed, create a tenant with a public name and one or more legal company identities:

{
  "name": "Example Energy",
  "company_id": [
    {
      "name": "Example Energy AB",
      "orgnr": "SE556840226601"
    }
  ]
}

Creating a tenant automatically adds it to the client scope. Authenticate again before making requests for the new tenant. Then add a square PNG icon between 256 and 512 pixels per side; leave clear space around the logo for the best recipient experience.

The endpoint returns 201 when a tenant is created and 200 when an existing tenant is found and added to the client scope. A 409 means that the company identity belongs to a tenant outside the client’s scope.

See the Create Tenant API reference for the precise contract.

Request access to an existing tenant

When POST /v2/tenant returns 409, use the Request access operation to post the existing tenant’s VAT number:

POST /v2/tenant/request_access

{
  "vat_number": "SE556840226601"
}

Save the returned requestKey, then poll the request status:

GET /v2/tenant/request_access/{requestKey}

Access is granted or denied asynchronously. Continue only when the status is accepted or rejected. After an access request is accepted, authenticate again to obtain a token with the updated tenant scope before sending content.

For complete schemas, response codes, and required scopes, use the Tenant API reference.