Update README.md

README.md

@@ -1,3 +1,63 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+---
+
+# Token vs. Resource Group Access Rights Demo
+
+## Purpose
+This README explains how to set up a quick test to demonstrate how fine-grained tokens interact with resource group permissions in Hugging Face.
+
+## The Question We're Answering
+If a user has access to a model through a resource group, but their fine-grained token doesn't explicitly mention that model, will an API request to write to the model succeed?
+
+## Materials Needed
+- Hugging Face account with Enterprise access
+- Admin rights to create resource groups
+- Permission to create models and tokens
+
+## Setup Steps
+
+### 1. Create a Test Model
+1. Go to your Hugging Face profile
+2. Click "New Model"
+3. Name it "token-test-model" (or similar)
+
+### 2. Create a Resource Group
+1. Go to your organization settings
+2. Navigate to Resource Groups
+3. Create a new resource group named "token-test-group"
+4. Add your test model to this resource group
+5. Add yourself as a user with write permissions to this resource group
+
+### 3. Create a Fine-Grained Token
+1. Go to your profile settings (top right icon on the HF page - NOT your organization settings) > select Access Tokens
+2. Click "Create new Token"
+3. Select "Fine-grained" as token type
+4. Give it a name like "limited-test-token"
+5. Important: DO NOT select your test model or check any global repository permissions
+6. This token will have minimal, read access to public repositories (which is the default for any token, as noted in the UI: "The token will always have read access to all public repos contents").
+7. Create the token and save the value on the next screen for testing
+
+### 4. Test the Token
+1. Use the API Playground (https://huggingface.co/spaces/enzostvs/hub-api-playground)
+2. Set up a POST request to `/api/repos/create-commit`
+3. Add your fine-grained token in Headers (Authorization: Bearer YOUR_TOKEN)
+4. Use this JSON in Parameters:
+   ```json
+   {
+     "repo_id": "YOUR_ORG/token-test-model",
+     "repo_type": "model",
+     "commit_message": "Testing token permissions",
+     "operations": [
+       {
+         "operation": "create",
+         "path": "test.txt",
+         "content": "This is a permission test"
+       }
+     ]
+   }
+   ```
+5. Send the request - it should fail with a permission error
+
+## Expected Result
+The request will fail despite your user having access to the model through the resource group. This demonstrates that fine-grained tokens require explicit permissions, regardless of resource group access.