From e1fad97b451296359a7614096c2c31b030b5ea5a Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Wed, 22 Apr 2026 11:12:50 -0700
Subject: [PATCH] Document caller-supplied AccessKeyId/SecretAccessKey in
 CreateAccessKey

Adds a new "Caller-Supplied AccessKeyId and SecretAccessKey (Extension)"
section to Amazon-IAM-API.md covering the non-AWS extension landed in
PR seaweedfs/seaweedfs#9172: both-or-none rule, length/charset limits,
uniqueness requirement, and the curl-based invocation needed because
the AWS CLI does not expose these parameters. The CreateAccessKey row
in the actions table now links to the new section.

Also updates the MinIO comparison row in Supported-APIs-vs-Minio.md
to note that SeaweedFS exposes caller-supplied credentials on the
standard iam:CreateAccessKey action, while MinIO only offers it via
its proprietary svcacct admin API.
---
 Amazon-IAM-API.md          | 43 +++++++++++++++++++++++++++++++++++++-
 Supported-APIs-vs-Minio.md |  2 +-
 2 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/Amazon-IAM-API.md b/Amazon-IAM-API.md
index c9d5b20..b749e78 100644
--- a/Amazon-IAM-API.md
+++ b/Amazon-IAM-API.md
@@ -56,7 +56,7 @@ weed iam -filer=localhost:8888 -port=8111
 | `UpdateUser` | Update user properties | Admin only |
 | `ListUsers` | List all users | Admin only |
 | `SetUserStatus` | Enable or disable a user | Admin only |
-| `CreateAccessKey` | Create access key for user | Yes (own keys) |
+| `CreateAccessKey` | Create access key for user (supports optional caller-supplied `AccessKeyId`/`SecretAccessKey`, see [below](#caller-supplied-accesskeyid-and-secretaccesskey-extension)) | Yes (own keys) |
 | `DeleteAccessKey` | Delete access key | Yes (own keys) |
 | `UpdateAccessKey` | Change access key status (Active/Inactive) | Yes (own keys) |
 | `ListAccessKeys` | List access keys for user | Yes (own keys) |
@@ -131,6 +131,47 @@ aws --endpoint $AWS_ENDPOINT iam create-user --user-name alice
 aws --endpoint $AWS_ENDPOINT iam create-access-key --user-name alice
 ```
 
+### Caller-Supplied AccessKeyId and SecretAccessKey (Extension)
+
+SeaweedFS extends `CreateAccessKey` with two optional form parameters that are
+not part of the AWS IAM API: `AccessKeyId` and `SecretAccessKey`. When both are
+supplied, they are used verbatim instead of being randomly generated. This is
+useful when applications need stable, pre-known credentials — for example, when
+provisioning S3 secrets from an external source into a Kubernetes deployment.
+
+**Rules:**
+
+- Both parameters must be supplied together. Supplying only one is rejected
+  with `InvalidInput`.
+- `AccessKeyId`: 4–128 ASCII alphanumeric characters (`A-Z`, `a-z`, `0-9`).
+  The restriction prevents characters that would break AWS SigV4
+  canonicalization (e.g. `/`, `=`, `,`).
+- `SecretAccessKey`: 8–128 characters.
+- `AccessKeyId` must be unique across all identities and service accounts;
+  a collision returns `EntityAlreadyExists`.
+- Omit both to get the AWS-standard random-generation behavior.
+
+**The AWS CLI does not expose these parameters**, so callers must POST directly
+to the IAM endpoint. For example, using the standalone IAM API:
+
+```bash
+# The standalone IAM API listens on port 8111 by default.
+IAM_ENDPOINT=http://localhost:8111
+
+curl -X POST "$IAM_ENDPOINT" \
+  --data-urlencode "Action=CreateAccessKey" \
+  --data-urlencode "UserName=alice" \
+  --data-urlencode "AccessKeyId=my-app-key" \
+  --data-urlencode "SecretAccessKey=my-app-secret-value" \
+  --aws-sigv4 "aws:amz:us-east-1:iam" \
+  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY"
+```
+
+The embedded IAM in the S3 server accepts the same parameters on its IAM
+endpoint. `SecretAccessKey` is redacted from server logs regardless of log
+verbosity. The response format is identical to the AWS `CreateAccessKey`
+response.
+
 ### Attach a Policy to User
 
 ```bash
diff --git a/Supported-APIs-vs-Minio.md b/Supported-APIs-vs-Minio.md
index e9badb4..1dcc534 100644
--- a/Supported-APIs-vs-Minio.md
+++ b/Supported-APIs-vs-Minio.md
@@ -99,7 +99,7 @@ For group management specifically, MinIO supports broadly similar administration
 | `iam:ListUsers` | ✅ | ⚠️ Proprietary | MinIO: `mc admin user list` |
 | `iam:UpdateUser` | ✅ | ⚠️ Proprietary | |
 | `iam:SetUserStatus` | ✅ | ⚠️ Proprietary | MinIO: `mc admin user enable/disable` |
-| `iam:CreateAccessKey` | ✅ | ⚠️ Proprietary | MinIO: `mc admin user svcacct add` |
+| `iam:CreateAccessKey` | ✅ | ⚠️ Proprietary | SeaweedFS also accepts optional caller-supplied `AccessKeyId`/`SecretAccessKey` (extension). MinIO: `mc admin user svcacct add` |
 | `iam:DeleteAccessKey` | ✅ | ⚠️ Proprietary | MinIO: `mc admin user svcacct rm` |
 | `iam:ListAccessKeys` | ✅ | ⚠️ Proprietary | MinIO: `mc admin user svcacct ls` |
 | `iam:UpdateAccessKey` | ✅ | ⚠️ Proprietary | |