Tenants

In Rafiki, a tenant represents an isolated environment for an account servicing entity (ASE). Each tenant has its own set of resources, such as assets, peers, and wallet addresses, and its own configuration settings. This allows multiple ASEs to share a single Rafiki instance while maintaining data isolation and security. The purpose of this guide is to help you set up and manage tenants.

While this guide focuses on operators managing tenants from the Backend Admin API, the Rafiki Admin application offers the same capabilities in a user-friendly interface.

Refer to the Rafiki Admin user guide for detailed instructions and examples of creating and managing tenants through the application.

Tenant properties

Each tenant on a given Rafiki instance has the following properties:

Property	Description
`id`	Unique identifier for the tenant used in API requests and webhook events.
`email`	The tenant’s email address.
`apiSecret`	Secret used to HMAC-sign Backend Admin API requests (HMAC SHA-256) for this tenant.
`idpConsentUrl`	The tenant’s identity provider (IdP) consent URL used to redirect end-users for interactive grants (Open Payments).
`idpSecret`	Secret used to authenticate requests from the tenant’s IdP to Rafiki.
`publicName`	Public display name for the tenant (shown in the Rafiki Admin application).
`settings`	Key-value pairs for initial tenant settings. See the table below.

Tenant settings

Tenant settings allow operators to customize tenant behavior. These settings are stored as key-value pairs and can be managed via the Backend Admin API or the Rafiki Admin application.

Setting	Description
`EXCHANGE_RATES_URL`	The URL of the tenant’s exchange rates service. This setting is used to configure the source of exchange rate data for the tenant.
`WEBHOOK_URL`	The URL of the tenant’s webhook endpoint. This setting is used to configure the endpoint that will receive webhook events for the tenant.
`WEBHOOK_TIMEOUT`	The timeout for the tenant’s webhook requests (in milliseconds). This setting is used to configure the maximum amount of time to wait for a response from the webhook endpoint.
`WEBHOOK_MAX_RETRY`	The maximum number of retries for the tenant’s webhook event when a non-200 status is returned or if the request timed out.
`WALLET_ADDRESS_URL`	Base URL for wallet addresses created for the tenant. This setting cannot be updated once set.
`ILP_ADDRESS`	Base Interledger Protocol (ILP) address for the tenant.

Create a tenant

After you create a tenant, securely communicate the tenant id and apiSecret to the tenant out-of-band.

mutation CreateTenant($input: CreateTenantInput!) {
  createTenant(input: $input) {
    tenant {
      id
      publicName
      email
      apiSecret
      idpConsentUrl
      idpSecret
    }
  }
}

{
  "input": {
    "publicName": "Tenant Name",
    "email": "tenant@example.com",
    "apiSecret": "your-secret-api-key",
    "idpConsentUrl": "https://example.com/consent",
    "idpSecret": "your-idp-secret"
  }
}

For more information about this mutation’s input object, see CreateTenantInput.

{
  "data": {
    "createTenant": {
      "tenant": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "publicName": "Tenant Name",
        "email": "tenant@example.com",
        "apiSecret": "your-secret-api-key",
        "idpConsentUrl": "https://example.com/consent",
        "idpSecret": "your-idp-secret"
      }
    }
  }
}

Update a tenant

mutation UpdateTenant($input: UpdateTenantInput!) {
  updateTenant(input: $input) {
    tenant {
      id
      email
      apiSecret
      idpConsentUrl
      idpSecret
      publicName
    }
  }
}

{
  "input": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "publicName": "New Tenant Name",
    "email": "new-tenant@example.com",
    "idpConsentUrl": "https://example.com/new-consent",
    "idpSecret": "new-idp-secret"
  }
}

For more information about this mutation’s input object, see UpdateTenantInput.

{
  "data": {
    "updateTenant": {
      "tenant": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "publicName": "New Tenant Name",
        "email": "new-tenant@example.com",
        "apiSecret": "your-secret-api-key",
        "idpConsentUrl": "https://example.com/new-consent",
        "idpSecret": "new-idp-secret"
      }
    }
  }
}

Delete a tenant

mutation DeleteTenant($id: String!) {
  deleteTenant(id: $id) {
    success
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "data": {
    "deleteTenant": {
      "success": true
    }
  }
}