From 519173872f318b312700c39911254002ef246b48 Mon Sep 17 00:00:00 2001
From: Sven Krieger <37476281+svkrieger@users.noreply.github.com>
Date: Tue, 7 Jan 2025 15:57:43 +0100
Subject: [PATCH] Add shadow user creation to docs

---
 .../source/includes/api_resources/_users.erb  | 20 ++++++++
 .../includes/resources/roles/_create.md.erb   |  3 ++
 .../includes/resources/users/_create.md.erb   | 48 ++++++++++++++++---
 3 files changed, 64 insertions(+), 7 deletions(-)

diff --git a/docs/v3/source/includes/api_resources/_users.erb b/docs/v3/source/includes/api_resources/_users.erb
index 788e47448f9..cc8acbbd3d5 100644
--- a/docs/v3/source/includes/api_resources/_users.erb
+++ b/docs/v3/source/includes/api_resources/_users.erb
@@ -18,6 +18,26 @@
   }
 <% end %>
 
+<% content_for :single_user_with_custom_origin do %>
+  {
+    "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
+    "created_at": "2019-03-08T01:06:19Z",
+    "updated_at": "2019-03-08T01:06:19Z",
+    "username": "some-user",
+    "presentation_name": "some-user",
+    "origin": "some-origin",
+    "metadata": {
+      "labels": {},
+      "annotations":{}
+    },
+    "links": {
+      "self": {
+        "href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
+      }
+    }
+  }
+<% end %>
+
 <% content_for :single_user_with_metadata do %>
   {
     "guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
diff --git a/docs/v3/source/includes/resources/roles/_create.md.erb b/docs/v3/source/includes/resources/roles/_create.md.erb
index 5b7989b4cd9..d464d0917a3 100644
--- a/docs/v3/source/includes/resources/roles/_create.md.erb
+++ b/docs/v3/source/includes/resources/roles/_create.md.erb
@@ -85,6 +85,9 @@ For a user to be assigned a space role, the user must already have an organizati
 
 If the associated user is valid but does not exist in Cloud Controller's database, a user resource will be created automatically.
 
+If CAPI property `cc.allow_user_creation_by_org_manager` is enabled, the organization role is being created by username + origin and the user does not exist in UAA yet, the user will be created.
+The origin must be different from `uaa` in this case.
+
 #### Definition
 `POST /v3/roles`
 
diff --git a/docs/v3/source/includes/resources/users/_create.md.erb b/docs/v3/source/includes/resources/users/_create.md.erb
index 89066b3384c..0cd53eee872 100644
--- a/docs/v3/source/includes/resources/users/_create.md.erb
+++ b/docs/v3/source/includes/resources/users/_create.md.erb
@@ -5,6 +5,11 @@ Controller database.
 
 Generally, the GUID should match the GUID of an already-created user in the
 UAA database, though this is not required.
+Creating a user by guid is only permitted by admins.
+
+If CAPI property `cc.allow_user_creation_by_org_manager` is enabled, a UAA user will be automatically created if it does not exist yet.
+The UAA user will be only created when `username` and `origin` have been provided instead of a guid. Additionally `origin` must be different from `uaa`.
+Admins and OrgManagers can make use of the UAA user creation.
 
 ```
 Example Request
@@ -31,19 +36,48 @@ Content-Type: application/json
 <%= yield_content :single_user %>
 ```
 
+```
+Example Request (by username and origin)
+```
+
+```shell
+curl "https://api.example.org/v3/users" \
+  -X POST \
+  -H "Authorization: bearer [token]" \
+  -H "Content-type: application/json" \
+  -d '{
+    "username": "some-user",
+    "origin": "some-origin"
+  }'
+```
+
+```
+Example Response
+```
+
+```http
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+<%= yield_content :single_user_with_custom_origin %>
+```
+
 #### Definition
 `POST /v3/users`
 
 #### Required parameters
 
 Name     | Type     | Description
--------  | -------  | -----------
-**guid** | _string_ | Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user's GUID; in the case of UAA clients, this will match the UAA client ID                                                                                             |
-**metadata.labels**   | [_label object_](#links) | Labels applied to the user                                                                                                 |
-**metadata.annotations** | [_annotation object_](#links) | Annotations added to the user                                                                                      |
+-------  | -------  |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+**guid** | _string_ | Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user's GUID; in the case of UAA clients, this will match the UAA client ID |
+**username** | _string_ | Username of the user to be created. This can only be provided together with `origin`.                                                                                   |
+**origin** | _string_ | Origin of the user to be created. This can only be provided together with `username` and cannot be `uaa`.                                                               |
+**metadata.labels**   | [_label object_](#links) | Labels applied to the user                                                                                                                                              |
+**metadata.annotations** | [_annotation object_](#links) | Annotations added to the user                                                                                                                                           |
 
 #### Permitted roles
 
- |
------ |
-Admin |
+Role | Notes
+----- |----------------------------------------------------------------------------------------------------------------------------
+Admin |                                                                                                                            |
+OrgManager | can only create users by `username` and `origin` and when CAPI property `cc.allow_user_creation_by_org_manager` is enabled |