From b369772b009102e7543349ec1f6548f4792b03cd Mon Sep 17 00:00:00 2001 From: Pierrci Date: Fri, 4 Sep 2026 15:48:10 -0400 Subject: [PATCH 1/5] Update tokens management doc: token-id revoke API, 50 admin notifications Two sections drifted from the code: - The org revoke API now takes a token id (POST .../settings/tokens/:tokenId/revoke) instead of the raw token value in the body; the raw-value endpoint was removed in huggingface-internal/moon-landing#19474. Also: self-revoke now means "the token used for auth", stated as a 403. - Pending-token notifications go to up to 50 admins, not 5 (huggingface-internal/moon-landing#19496). Generated with Claude Code (GLM 5.3 Flash), agent acting for @Pierrci --- docs/hub/enterprise-tokens-management.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/docs/hub/enterprise-tokens-management.md b/docs/hub/enterprise-tokens-management.md index d874890bde..def0f25cc9 100644 --- a/docs/hub/enterprise-tokens-management.md +++ b/docs/hub/enterprise-tokens-management.md @@ -51,7 +51,7 @@ Team & Enterprise organization administrators can enforce the following policies ## Reviewing Token Authorization -When token policy is set to "Require administrator approval", organization administrators can review details of all fine-grained tokens accessing organization-owned resources and approve or deny access. When a new token enters the pending state, up to 5 organization administrators with confirmed email addresses receive a notification with a direct link to the token review page. No notification is sent when a token is auto-approved (e.g., because the creator is an org admin). +When token policy is set to "Require administrator approval", organization administrators can review details of all fine-grained tokens accessing organization-owned resources and approve or deny access. When a new token enters the pending state, up to 50 organization administrators with confirmed email addresses receive a notification with a direct link to the token review page. No notification is sent when a token is auto-approved (e.g., because the creator is an org admin). - **Pending** tokens are awaiting an administrator decision - **Approved** tokens have been authorized and are active @@ -102,21 +102,16 @@ Members whose tokens have been revoked receive a `403` error with the message: _ ### Revoking via API -Administrators can also revoke a token programmatically by providing the raw token value. This is useful for automated workflows such as secrets scanning, where a leaked token is detected and needs to be revoked immediately. +Administrators can also revoke a token programmatically using its token id. This is useful for automated workflows, where a token needs to be revoked immediately. ```bash # ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token -# LEAKED_HF_TOKEN should contain the raw token value to revoke -curl -X POST "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens/revoke" \ - -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \ - -H "Content-Type: application/json" \ - -d "{\"token\": \"${LEAKED_HF_TOKEN}\"}" +# TOKEN_ID is the 24-character id shown on the org token settings page (or returned by the tokens listing API) +curl -X POST "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens/${TOKEN_ID}/revoke" \ + -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" ``` -> [!TIP] -> To avoid leaking token values in shell history or logs, pass them via environment variables or files, and avoid pasting raw tokens directly into command lines. - -An administrator cannot revoke their own token (`LEAKED_HF_TOKEN` cannot have the same value as `ADMIN_HF_TOKEN` in the snippet above). +An administrator cannot revoke their own token: a request whose token id matches the token used for authentication is rejected with a `403` error. > [!NOTE] > This endpoint only revokes the token's access to your organization; the token keeps working for its owner's other resources. To invalidate a leaked token everywhere, use [`POST /api/credentials/revoke`](./security-tokens#revoking-a-leaked-token) instead, which requires no authentication and accepts a batch of raw token values. From dbfe5fff5ee36dc25e9699c431722387e13567bd Mon Sep 17 00:00:00 2001 From: Pierrci Date: Fri, 4 Sep 2026 15:51:27 -0400 Subject: [PATCH 2/5] Document the org tokens listing API Add a "Listing Tokens via API" section: GET /api/organizations/:name/settings/tokens (auth, response fields, Link-header pagination, q filter with status:all), matching GET /api/organizations/:name/settings/tokens in moon-landing. Generated with Claude Code (GLM 5.3 Flash), agent acting for @Pierrci --- docs/hub/enterprise-tokens-management.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/hub/enterprise-tokens-management.md b/docs/hub/enterprise-tokens-management.md index def0f25cc9..3a03f3f494 100644 --- a/docs/hub/enterprise-tokens-management.md +++ b/docs/hub/enterprise-tokens-management.md @@ -100,6 +100,23 @@ Revoked tokens remain revoked even if the organization's token policy is later c Members whose tokens have been revoked receive a `403` error with the message: _"Your token has been revoked by the organization administrator, you can no longer access organization resources. Please contact them for more information."_ This message is shown regardless of whether the organization uses the "Require administrator approval" policy. +### Listing Tokens via API + +> [!WARNING] +> This feature is part of the Team & Enterprise plans. + +The token listing shown in the settings UI is also available programmatically: + +```bash +# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token +curl -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \ + "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens" +``` + +The response is an array of member access tokens, with the token id (`_id`), kind (`role`: `read`, `write` or `fineGrained`), last 4 characters (`last4`), creation date (`createdAt`), last-used date (`lastUsedAt`, absent if never used), owner and authorization status (`pending`, `approved`, `denied` or `revoked`). Fine-grained tokens also include their specific permissions. + +Pagination uses the `Link` header (`rel="next"`, up to 100 tokens per page). The `q` parameter filters the list on `owner:`, `role:`, `status:` and `token:` (last 4 characters), each negatable with `-`; by default, revoked tokens are hidden. Pass `q=status:all` to include them, like the **Show revoked tokens** toggle in the UI. + ### Revoking via API Administrators can also revoke a token programmatically using its token id. This is useful for automated workflows, where a token needs to be revoked immediately. From bd5942894722d1ecc61fda99f6a7ef50b29770f0 Mon Sep 17 00:00:00 2001 From: Pierrci Date: Fri, 4 Sep 2026 15:58:26 -0400 Subject: [PATCH 3/5] Trim listing section: OpenAPI link for schema, drop pagination detail Generated with Claude Code (GLM 5.3 Flash), agent acting for @Pierrci --- docs/hub/enterprise-tokens-management.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/hub/enterprise-tokens-management.md b/docs/hub/enterprise-tokens-management.md index 3a03f3f494..026ede30b9 100644 --- a/docs/hub/enterprise-tokens-management.md +++ b/docs/hub/enterprise-tokens-management.md @@ -113,9 +113,9 @@ curl -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \ "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens" ``` -The response is an array of member access tokens, with the token id (`_id`), kind (`role`: `read`, `write` or `fineGrained`), last 4 characters (`last4`), creation date (`createdAt`), last-used date (`lastUsedAt`, absent if never used), owner and authorization status (`pending`, `approved`, `denied` or `revoked`). Fine-grained tokens also include their specific permissions. +The response is an array of member access tokens. See the OpenAPI reference for the full schema: GET /api/organizations//settings/tokens -Pagination uses the `Link` header (`rel="next"`, up to 100 tokens per page). The `q` parameter filters the list on `owner:`, `role:`, `status:` and `token:` (last 4 characters), each negatable with `-`; by default, revoked tokens are hidden. Pass `q=status:all` to include them, like the **Show revoked tokens** toggle in the UI. +By default, revoked tokens are hidden; pass `q=status:all` to include them, like the **Show revoked tokens** toggle in the UI. ### Revoking via API From 5ee054cd195fef11f2d21da7a58733e01089b9ae Mon Sep 17 00:00:00 2001 From: Pierrci Date: Fri, 4 Sep 2026 16:05:06 -0400 Subject: [PATCH 4/5] Move Listing Tokens via API to its own top-level section Listing is a standalone feature; it was nested under Revoking Tokens. Generated with Claude Code (GLM 5.3 Flash), agent acting for @Pierrci --- docs/hub/enterprise-tokens-management.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/hub/enterprise-tokens-management.md b/docs/hub/enterprise-tokens-management.md index 026ede30b9..6ef225d104 100644 --- a/docs/hub/enterprise-tokens-management.md +++ b/docs/hub/enterprise-tokens-management.md @@ -89,18 +89,7 @@ Administrators have two ways to remove a token's access to an organization: Use **deny** when managing access within the approval workflow (the token transitions to a `denied` state and can be re-approved later). Use **revoke** when you need to permanently cut off a token's access to the organization. -## Revoking Tokens - -> [!WARNING] -> This feature is part of the Enterprise plan and above. - -Organization administrators can revoke any member's access token from the token detail page. Revocation is available regardless of whether the organization uses the "Require administrator approval" policy. A revoked token can no longer access the organization's resources, but continues to work elsewhere. The token owner receives an email notification upon revocation. - -Revoked tokens remain revoked even if the organization's token policy is later changed or disabled. Revocation is permanent at the organization level — there is no un-revoke action. If a member needs access restored, they must delete the revoked token and create a new one. If the organization uses the "Require administrator approval" policy, the new token will start in the pending state and require admin approval. - -Members whose tokens have been revoked receive a `403` error with the message: _"Your token has been revoked by the organization administrator, you can no longer access organization resources. Please contact them for more information."_ This message is shown regardless of whether the organization uses the "Require administrator approval" policy. - -### Listing Tokens via API +## Listing Tokens via API > [!WARNING] > This feature is part of the Team & Enterprise plans. @@ -117,6 +106,17 @@ The response is an array of member access tokens. See the OpenAPI reference for By default, revoked tokens are hidden; pass `q=status:all` to include them, like the **Show revoked tokens** toggle in the UI. +## Revoking Tokens + +> [!WARNING] +> This feature is part of the Enterprise plan and above. + +Organization administrators can revoke any member's access token from the token detail page. Revocation is available regardless of whether the organization uses the "Require administrator approval" policy. A revoked token can no longer access the organization's resources, but continues to work elsewhere. The token owner receives an email notification upon revocation. + +Revoked tokens remain revoked even if the organization's token policy is later changed or disabled. Revocation is permanent at the organization level — there is no un-revoke action. If a member needs access restored, they must delete the revoked token and create a new one. If the organization uses the "Require administrator approval" policy, the new token will start in the pending state and require admin approval. + +Members whose tokens have been revoked receive a `403` error with the message: _"Your token has been revoked by the organization administrator, you can no longer access organization resources. Please contact them for more information."_ This message is shown regardless of whether the organization uses the "Require administrator approval" policy. + ### Revoking via API Administrators can also revoke a token programmatically using its token id. This is useful for automated workflows, where a token needs to be revoked immediately. From 99b328e15aca67558121dfb6f59981b8d9b3c009 Mon Sep 17 00:00:00 2001 From: Pierrci Date: Fri, 4 Sep 2026 16:10:36 -0400 Subject: [PATCH 5/5] Drop redundant Team & Enterprise warning on listing section Page-top warning already covers the feature; per-section warnings only mark the Enterprise-only pieces (revocation). Generated with Claude Code (GLM 5.3 Flash), agent acting for @Pierrci --- docs/hub/enterprise-tokens-management.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/hub/enterprise-tokens-management.md b/docs/hub/enterprise-tokens-management.md index 6ef225d104..1121a9a145 100644 --- a/docs/hub/enterprise-tokens-management.md +++ b/docs/hub/enterprise-tokens-management.md @@ -91,9 +91,6 @@ Use **deny** when managing access within the approval workflow (the token transi ## Listing Tokens via API -> [!WARNING] -> This feature is part of the Team & Enterprise plans. - The token listing shown in the settings UI is also available programmatically: ```bash