Service Tokens

[davlgd]

📝 What does this PR do?

This PR updates documentation to mention service tokens

---

🧪 Type of Change

• ⚠️ Bug fix
• 📅 Changelog update
• 📚 Documentation update
• ✨ New content/feature
• 🔧 Technical/maintenance

---

✅ Quick Checklist

• I have read the contributing guidelines
• The content is accurate and links work
• The site builds without errors

---

👥 Reviewers

@hsablonniere
@judu

[github-actions]

✅ Review app deployed

Check how your changes look like!

ℹ️ Name	🔗 Infos & links
🌱 Latest deployed commit	904b96b
👁️ Preview	https://documentation-PR-911.cleverapps.io/developers

[Copilot]

Pull request overview

Updates the documentation to introduce and describe service tokens as an additional authentication mechanism, including their role-based permissions and usage from both Clever Tools and the API.

Changes:

• Add “service tokens” to keywords and organisation roles/privileges documentation.
• Extend the API overview to document service tokens, including a comparison table vs API tokens and OAuth 1.
• Add a detailed “Service tokens” section covering creation, usage, and Biscuit inspection/attenuation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
content/doc/account/organisations.md	Adds service tokens to keywords and the roles/privileges table, plus a note about role assignment limits when creating tokens.
content/api/howto.md	Adds service tokens as a third authentication mechanism, documents how to create/use them, and includes a feature comparison table.

[Copilot]

The OAuth 1 max lifetime is stated as "3 months", but the existing documentation states OAuth tokens last 1 year when created via Clever Tools and 3 months via Console/other integrations. Consider updating this row (or adding a footnote) to reflect that lifetime depends on how the OAuth token is created, to avoid contradicting the changelog entry.

Suggested change

	| **Max lifetime** | 1 year | 3 months | 1 year (default: 90 days) |
	| **Role-based** | No | No (permission-based) | Yes (Admin, Manager, Developer, Accounting) |
	| **API endpoint** | API Bridge only | Main API (v2, v4) | Main API (v2) |
	| **Best for** | Personal scripts, CLI | Third-party apps | CI/CD, automation, M2M |
	| **Max lifetime** | 1 year | Depends on how you create it* | 1 year (default: 90 days) |
	| **Role-based** | No | No (permission-based) | Yes (Admin, Manager, Developer, Accounting) |
	| **API endpoint** | API Bridge only | Main API (v2, v4) | Main API (v2) |
	| **Best for** | Personal scripts, CLI | Third-party apps | CI/CD, automation, M2M |
	\* OAuth 1 tokens last up to 1 year when you create them with Clever Tools, and up to 3 months when you create them from the Console or other integrations.

[judu]

Peut être un lien un peu plus direct vers un « comment installer la cli biscuit » ?

[judu]

Pour git push, un truc qui fonctionne à 100% :

; cat > /tmp/askpass.sh <<EOF
echo "<the biscuit>"
EOF

; chmod +x /tmp/askpass.sh
; git remote add deploy-cc https://push-par-….services.clever-cloud.com/app_babe00000….git # NOTE THE https url
; GIT_ASKPASS=/tmp/askpass.sh git push deploy-cc HEAD:master

J’ai pas complètement testé ça mais :

git remote add deploy-cc https://<biscuit>:unused@push-par-….services.clever-cloud.com/app_babe0000….git

git push deploy-cc HEAD:master

Ça devrait marcher.

note : c’est la même basic auth que le git push https qu’on fait déjà avec les tokens oauth. Le twist c’est qu’il faut mettre le biscuit en username de l’auth !

La méthode git askpass fait que le script est appelé deux fois je crois et on envoie le push avec Authorization: Basic base64(<biscuit>:<biscuit>) et le "password" est ignoré côté serveur.