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

Use the createTenant mutation to register a new tenant within your Rafiki instance.

This operation is restricted to operators. When a new tenant is created, Rafiki automatically assigns a default ILP address, applies standard configuration settings, and registers the tenant with the auth service. Operators can also provide initial custom settings during creation.

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

Use the updateTenant mutation to modify an existing tenant’s configuration.

Tenants can update their own profile details such as the public name, contact email, or identity provider URLs. Tenants can also rotate their own apiSecret using this mutation. Operators can update any tenant’s information, but cannot modify a tenant’s apiSecret on their behalf.

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

Use the deleteTenant mutation to remove a tenant from Rafiki. Only operators can perform this action.

Deleting a tenant marks the tenant as deleted and removes all associated tenant settings and authentication entries. After deletion, the tenant can no longer be used to create or manage resources in Rafiki.

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

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

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