From 780f022c4389d1f86ccb37e70c63127c26c96dcf Mon Sep 17 00:00:00 2001
From: Jaime Melis <jmelis@redhat.com>
Date: Tue, 26 Nov 2024 11:44:53 +0100
Subject: [PATCH 1/2] Document tenancy design

---
 src/content/docs/inventory/inventory-api.md | 23 ++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/src/content/docs/inventory/inventory-api.md b/src/content/docs/inventory/inventory-api.md
index 50afc9f..81d99dc 100644
--- a/src/content/docs/inventory/inventory-api.md
+++ b/src/content/docs/inventory/inventory-api.md
@@ -33,12 +33,23 @@ The request body is the resource type. This top level json object is comprised o
 
 Required data is marked with an asterisk (*).
 
+#### Tenancy
+
+All resources registered in Inventory must contain tenancy information. This information is used to determine in which Kessel workspace the resource will be registered.
+
+Clients of Inventory have two alternatives to provide this tenancy information. If the client sets either _workspace_ or _workspace_id_ in the _metadata_ section, the Inventory will attempt to store the resource in that specific workspace.
+
+If the client omits this information, Inventory will use extract the organization ID from the token, and derive the default workspace that corresponds to that organization.
+
+Note that in both cases Inventory will verify that the token has authorization to register the resource in the target workspace.
+
 #### Metadata
 
 This object represents the attributes that are common for all resources, no matter the type. The information that a reporter provides for this object is:
 
-* _**org_id***_
-* _**workspace_id**_
+* One of:
+  * _**workspace**_ - this identifies the workspace by name
+  * _**workspace_id**_ - this identifies the workspace by ID
 * _**labels**_
 
 Most of the metadata is generated by the Asset Inventory service, i.e.
@@ -143,11 +154,17 @@ The JSON for the resource-relationship is similar to resources, i.e.
 }
 ```
 
+#### Tenancy
+
+The tenancy considerations for relationships are the same as the ones documented above for reporting new resources.
+
 #### Metadata
 
 This object represents the attributes that are common for all resource relationships, no matter the type. The information that a reporter provides for this object is:
 
-* _**org_id***_
+* One of:
+  * _**workspace**_ - this identifies the workspace by name
+  * _**workspace_id**_ - this identifies the workspace by ID
 
 Most of the metadata is generated by the Asset Inventory service, i.e.
 

From c84b56b4345f4a64752ad98317ad0b4889e333e9 Mon Sep 17 00:00:00 2001
From: Jaime Melis <jmelis@redhat.com>
Date: Tue, 26 Nov 2024 11:48:45 +0100
Subject: [PATCH 2/2] Adds a TOC

---
 src/content/docs/inventory/inventory-api.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/content/docs/inventory/inventory-api.md b/src/content/docs/inventory/inventory-api.md
index 81d99dc..0f37c66 100644
--- a/src/content/docs/inventory/inventory-api.md
+++ b/src/content/docs/inventory/inventory-api.md
@@ -2,6 +2,26 @@
 title: Kessel Asset Inventory APIs
 ---
 
+- [Reporting a New Resource to Asset Inventory](#reporting-a-new-resource-to-asset-inventory)
+  - [The Request Body](#the-request-body)
+    - [Tenancy](#tenancy)
+    - [Metadata](#metadata)
+    - [Reporter\_data](#reporter_data)
+      - [Multiple Reporters](#multiple-reporters)
+    - [Resource\_data](#resource_data)
+  - [Resource Deduplication](#resource-deduplication)
+- [Resource Lifecycle](#resource-lifecycle)
+  - [Resource Identification](#resource-identification)
+- [Reporting a New Relationship Between 2 Resources](#reporting-a-new-relationship-between-2-resources)
+  - [The Request Body](#the-request-body-1)
+    - [Tenancy](#tenancy-1)
+    - [Metadata](#metadata-1)
+    - [Reporter\_data](#reporter_data-1)
+    - [Reporter\_data](#reporter_data-2)
+      - [Multiple Reporters](#multiple-reporters-1)
+    - [Relationship\_data](#relationship_data)
+  - [Relationship Lifecycle](#relationship-lifecycle)
+
 This document does not supersede any information in the API specification. This is meant to help explain why the API works the way that it does. In other words, think of the API specification as the API “syntax” documentation and this as the API “semantics” documentation.
 
 **Notes:**