From 5f395195cb6820921a2b1d039e5174ec2d929cc2 Mon Sep 17 00:00:00 2001 From: brad-dow <162852233+brad-dow@users.noreply.github.com> Date: Wed, 10 Dec 2025 13:47:06 -0600 Subject: [PATCH 1/5] docs: update tenants, assets, and admin user guide Updated assets.mdx with sections for updating and deleting assets Updated tenants.mdx to include more contextual information before each operation (add, update, delete) Updated the admin user guide to specify read-only values when editing Overall, improvements made for multi-tenancy consistency and cohesion across pages --- .../content/docs/admin/admin-user-guide.mdx | 4 + .../docs/integration/requirements/assets.mdx | 149 ++++++++++++++++++ .../docs/integration/requirements/tenants.mdx | 12 ++ 3 files changed, 165 insertions(+) diff --git a/packages/documentation/src/content/docs/admin/admin-user-guide.mdx b/packages/documentation/src/content/docs/admin/admin-user-guide.mdx index c1342c39c4..d82c75df11 100644 --- a/packages/documentation/src/content/docs/admin/admin-user-guide.mdx +++ b/packages/documentation/src/content/docs/admin/admin-user-guide.mdx @@ -266,6 +266,10 @@ While the Edit Asset page shares fields with the Create Asset page, it also incl After editing any of the preceding fields in the General Information or Sending Fee sections, select **Save** to commit those changes. +:::note +The asset code and scale cannot be modified after creation. These fields remain read-only when viewing or editing an existing asset. +::: + #### Delete asset The final section of the Edit Asset page is the irreversible action of deleting an asset. Select **Delete asset** to make this change. diff --git a/packages/documentation/src/content/docs/integration/requirements/assets.mdx b/packages/documentation/src/content/docs/integration/requirements/assets.mdx index 8d9af55c24..405f4a02bf 100644 --- a/packages/documentation/src/content/docs/integration/requirements/assets.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/assets.mdx @@ -22,6 +22,8 @@ An asset represents an item of value that can be transferred via the Interledger ## Add an asset +Use the `createAsset` mutation to register a new asset with your Rafiki instance. + ```graphql @@ -81,3 +83,150 @@ The `asset` object in the response will include the `tenantId` of the tenant to + +## Update an asset + +Once an asset has been created, you may need to adjust its operational threshold values. +You can use the `updateAsset` mutation to modify the `withdrawalThreshold` and `liquidityThreshold`. + +These thresholds influence when Rafiki triggers low‑liquidity notifications but do not directly deposit or withdraw asset liquidity. + +For information about adding or removing liquidity, see [Asset liquidity](/admin/liquidity/asset-liquidity). + + + + ```graphql + mutation UpdateAsset($input: UpdateAssetInput!) { + updateAsset(input: $input) { + asset { + id + code + scale + withdrawalThreshold + liquidityThreshold + tenantId + } + } + } + ``` + + + + The input object for the update operation requires the asset `id`. + Only the threshold fields are editable; all other fields are immutable. + + ```json + { + "input": { + "id": "b3dffeda-1e0e-47d4-82a3-69b1a622eeb9", + "withdrawalThreshold": 100, + "liquidityThreshold": 500 + } + } + ``` + + For more information about this mutation’s input object, see [`UpdateAssetInput`](/apis/graphql/backend/#definition-UpdateAssetInput). + + :::note[Tenant ID and HMAC-signed request headers] + + ::: + + + + ```json + { + "data": { + "updateAsset": { + "asset": { + "id": "b3dffeda-1e0e-47d4-82a3-69b1a622eeb9", + "code": "USD", + "scale": 2, + "withdrawalThreshold": 100, + "liquidityThreshold": 500, + "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + } + } + } + } + ``` + +:::note[Tenant ID in the asset response] +The `asset` object in the response will include the `tenantId` of the tenant to which the asset belongs. This `tenantId` is used to identify the tenant when processing requests related to the asset. +::: + + + + +--- + +## Delete an asset + +Deleting an asset removes it from active use within a Rafiki instance. + +This operation succeeds only if the asset is **not** referenced by any peers or wallet addresses. + +:::danger +Deleting an asset is permanent and cannot be reversed. + +You can only delete an asset if: + +- No peers reference the asset +- No wallet addresses are associated with it + +If the asset is still in use, the backend prevents deletion and returns an error. +::: + + + + ```graphql + mutation DeleteAsset($input: DeleteAssetInput!) { + deleteAsset(input: $input) { + asset { + id + code + scale + tenantId + } + } + } + ``` + + + + ```json + { + "input": { + "id": "b3dffeda-1e0e-47d4-82a3-69b1a622eeb9" + } + } + ``` + + For more information about this mutation’s input object, see [`DeleteAssetInput`](/apis/graphql/backend/#definition-DeleteAssetInput). + + :::note[Tenant ID and HMAC-signed request headers] + + ::: + + + + ```json + { + "data": { + "deleteAsset": { + "asset": { + "id": "b3dffeda-1e0e-47d4-82a3-69b1a622eeb9", + "code": "USD", + "scale": 2, + "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + } + } + } + } + ``` + +:::note[Tenant ID in the asset response] +The `asset` object in the response will include the `tenantId` of the tenant to which the asset belongs. This `tenantId` is used to identify the tenant when processing requests related to the asset. +::: + + + \ No newline at end of file diff --git a/packages/documentation/src/content/docs/integration/requirements/tenants.mdx b/packages/documentation/src/content/docs/integration/requirements/tenants.mdx index 7be3a1e5fd..b399148966 100644 --- a/packages/documentation/src/content/docs/integration/requirements/tenants.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/tenants.mdx @@ -54,6 +54,10 @@ Only operators can create, edit, and delete tenants. ## 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. @@ -111,6 +115,10 @@ After you create a tenant, securely communicate the tenant `id` and `apiSecret` ## 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. Operators can update any tenant’s information except for the `apiSecret`, which cannot be changed through this mutation. + ```graphql @@ -166,6 +174,10 @@ After you create a tenant, securely communicate the tenant `id` and `apiSecret` ## 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. + ```graphql From 06ae71466627ef76aff87fab01c6bf1e6d91cc96 Mon Sep 17 00:00:00 2001 From: brad-dow <162852233+brad-dow@users.noreply.github.com> Date: Wed, 10 Dec 2025 13:49:56 -0600 Subject: [PATCH 2/5] docs: prettier i forgot my old friend, prettier --- .../src/content/docs/integration/requirements/assets.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/documentation/src/content/docs/integration/requirements/assets.mdx b/packages/documentation/src/content/docs/integration/requirements/assets.mdx index 405f4a02bf..24dcfbb464 100644 --- a/packages/documentation/src/content/docs/integration/requirements/assets.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/assets.mdx @@ -130,6 +130,7 @@ For information about adding or removing liquidity, see [Asset liquidity](/admin :::note[Tenant ID and HMAC-signed request headers] ::: + @@ -170,8 +171,8 @@ Deleting an asset is permanent and cannot be reversed. You can only delete an asset if: -- No peers reference the asset -- No wallet addresses are associated with it +- No peers reference the asset +- No wallet addresses are associated with it If the asset is still in use, the backend prevents deletion and returns an error. ::: @@ -206,6 +207,7 @@ If the asset is still in use, the backend prevents deletion and returns an error :::note[Tenant ID and HMAC-signed request headers] ::: + @@ -229,4 +231,4 @@ The `asset` object in the response will include the `tenantId` of the tenant to ::: - \ No newline at end of file + From cde116badf47835baac4a3bb6d0790f9ad15513b Mon Sep 17 00:00:00 2001 From: brad-dow <162852233+brad-dow@users.noreply.github.com> Date: Thu, 11 Dec 2025 14:12:23 -0600 Subject: [PATCH 3/5] docs: refine based on Melissa's feedback - Updated user guide and tenants page to clarify API secret details - Revised ambiguous wording and accidental line break - Revised permissions lists on assets and peers pages --- .../content/docs/admin/admin-user-guide.mdx | 4 ++-- .../docs/integration/requirements/assets.mdx | 24 ++++++++++++------- .../docs/integration/requirements/peers.mdx | 18 +++++++++----- .../docs/integration/requirements/tenants.mdx | 2 +- 4 files changed, 30 insertions(+), 18 deletions(-) diff --git a/packages/documentation/src/content/docs/admin/admin-user-guide.mdx b/packages/documentation/src/content/docs/admin/admin-user-guide.mdx index d82c75df11..ca71e2cd7c 100644 --- a/packages/documentation/src/content/docs/admin/admin-user-guide.mdx +++ b/packages/documentation/src/content/docs/admin/admin-user-guide.mdx @@ -196,9 +196,9 @@ The Edit Tenant page includes the following sections: | | Email | The tenant's email address. | | Identity Provider Information | Consent URL | The URL for the tenant's identity provider consent endpoint. | | | Secret | The secret for the tenant's identity provider. | -| Sensitive Information | API Secret | A unique identifier assigned by Rafiki when the tenant was created. This cannot be changed. | +| Sensitive Information | API Secret | The tenant's API credential used to authenticate requests. Read-only for operators. | -You can modify the public name, email, consent URL, and secret for a tenant. The tenant ID and API secret are read-only. +You can modify the public name, email, consent URL, and secret for a tenant. The tenant ID cannot be changed. The API secret is read-only for operators but can be rotated by the tenants when logged in under their own account. After editing any of the preceding fields, select **Save** to commit those changes. diff --git a/packages/documentation/src/content/docs/integration/requirements/assets.mdx b/packages/documentation/src/content/docs/integration/requirements/assets.mdx index 24dcfbb464..dd8768b157 100644 --- a/packages/documentation/src/content/docs/integration/requirements/assets.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/assets.mdx @@ -13,12 +13,19 @@ An asset represents an item of value that can be transferred via the Interledger **Permissions** -- Operators can create assets for any tenant -- Operators can view any asset -- Operators can edit and delete assets that belong to any tenant -- Tenants can only view their own assets -- Tenants can only edit and delete their own assets -- Tenants cannot create assets +Operators can: + +- Create assets for any tenant +- View any asset +- Edit and delete assets that belong to any tenant + +Tenants can: + +- View their own assets +- Edit and delete their own assets + + +Tenants cannot create assets. ## Add an asset @@ -112,8 +119,7 @@ For information about adding or removing liquidity, see [Asset liquidity](/admin - The input object for the update operation requires the asset `id`. - Only the threshold fields are editable; all other fields are immutable. + The input object for the update operation requires the asset `id`. Only the threshold fields are editable; all other fields are immutable. ```json { @@ -164,7 +170,7 @@ The `asset` object in the response will include the `tenantId` of the tenant to Deleting an asset removes it from active use within a Rafiki instance. -This operation succeeds only if the asset is **not** referenced by any peers or wallet addresses. +You can only delete an asset if it's not associated with any peers or wallet addresses. Rafiki prevents deleting any asset that's still in use. :::danger Deleting an asset is permanent and cannot be reversed. diff --git a/packages/documentation/src/content/docs/integration/requirements/peers.mdx b/packages/documentation/src/content/docs/integration/requirements/peers.mdx index 3187146362..d1c7e3f8d7 100644 --- a/packages/documentation/src/content/docs/integration/requirements/peers.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/peers.mdx @@ -21,12 +21,18 @@ Whether you are using the Backend Admin API or the Rafiki Admin application, the **Permissions** -- Operators can create peers for any tenant -- Operators can view any peer -- Operators can edit and delete peers that belong to any tenant -- Tenants can only view their own peers -- Tenants can only edit and delete their own peers -- Tenants cannot create peers +Operators can: + +- Create peers for any tenant +- View any peer +- Edit and delete peers that belong to any tenant + +Tenants can: + +- View their own peers +- Edit and delete their own peers + +Tenants cannot create peers. ## Perform prerequisites diff --git a/packages/documentation/src/content/docs/integration/requirements/tenants.mdx b/packages/documentation/src/content/docs/integration/requirements/tenants.mdx index b399148966..105c428cd6 100644 --- a/packages/documentation/src/content/docs/integration/requirements/tenants.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/tenants.mdx @@ -117,7 +117,7 @@ After you create a tenant, securely communicate the tenant `id` and `apiSecret` 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. Operators can update any tenant’s information except for the `apiSecret`, which cannot be changed through this mutation. +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. From 526633304d952256fca49757edfda5b6071b2a4f Mon Sep 17 00:00:00 2001 From: brad-dow <162852233+brad-dow@users.noreply.github.com> Date: Thu, 11 Dec 2025 14:23:25 -0600 Subject: [PATCH 4/5] docs: fix lines another missed line break --- .../src/content/docs/integration/requirements/assets.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/documentation/src/content/docs/integration/requirements/assets.mdx b/packages/documentation/src/content/docs/integration/requirements/assets.mdx index dd8768b157..29d797bd5d 100644 --- a/packages/documentation/src/content/docs/integration/requirements/assets.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/assets.mdx @@ -93,8 +93,7 @@ The `asset` object in the response will include the `tenantId` of the tenant to ## Update an asset -Once an asset has been created, you may need to adjust its operational threshold values. -You can use the `updateAsset` mutation to modify the `withdrawalThreshold` and `liquidityThreshold`. +Once an asset has been created, you may need to adjust its operational threshold values. You can use the `updateAsset` mutation to modify the `withdrawalThreshold` and `liquidityThreshold`. These thresholds influence when Rafiki triggers low‑liquidity notifications but do not directly deposit or withdraw asset liquidity. From 072d911fd067fb9998e531a0514454a8b280f918 Mon Sep 17 00:00:00 2001 From: brad-dow <162852233+brad-dow@users.noreply.github.com> Date: Fri, 12 Dec 2025 16:11:11 -0600 Subject: [PATCH 5/5] docs: permissions tune-up Fixed permissions style and formatting on assets and peers pages --- .../docs/integration/requirements/assets.mdx | 14 ++------------ .../docs/integration/requirements/peers.mdx | 13 ++----------- 2 files changed, 4 insertions(+), 23 deletions(-) diff --git a/packages/documentation/src/content/docs/integration/requirements/assets.mdx b/packages/documentation/src/content/docs/integration/requirements/assets.mdx index 29d797bd5d..0f8182e230 100644 --- a/packages/documentation/src/content/docs/integration/requirements/assets.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/assets.mdx @@ -13,19 +13,9 @@ An asset represents an item of value that can be transferred via the Interledger **Permissions** -Operators can: +Operators can create, view, edit, and delete both their own assets and those that belong to any tenant. -- Create assets for any tenant -- View any asset -- Edit and delete assets that belong to any tenant - -Tenants can: - -- View their own assets -- Edit and delete their own assets - - -Tenants cannot create assets. +Tenants can view, edit, and delete only their own assets. They cannot create assets. ## Add an asset diff --git a/packages/documentation/src/content/docs/integration/requirements/peers.mdx b/packages/documentation/src/content/docs/integration/requirements/peers.mdx index d1c7e3f8d7..2288072b8a 100644 --- a/packages/documentation/src/content/docs/integration/requirements/peers.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/peers.mdx @@ -21,18 +21,9 @@ Whether you are using the Backend Admin API or the Rafiki Admin application, the **Permissions** -Operators can: +Operators can create, view, edit, and delete both their own peers and those that belong to any tenant. -- Create peers for any tenant -- View any peer -- Edit and delete peers that belong to any tenant - -Tenants can: - -- View their own peers -- Edit and delete their own peers - -Tenants cannot create peers. +Tenants can view, edit, and delete only their own peers. They cannot create peers. ## Perform prerequisites