From a30d86e6c3bb0c772a2d4b2f2ebb354f2dc3b5c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Brunat?= Date: Tue, 25 Aug 2026 10:36:04 +0200 Subject: [PATCH 1/3] api(service-tokens): document organisation service tokens Add a page covering organisation service tokens: scope and limitations, the CRUD endpoints under /v2/organisations/{id}/service-tokens, token creation fields, bearer and git-over-HTTP authentication, and security boundaries. Link the page from the API index and list service tokens alongside API tokens and OAuth 1 in the API overview. --- content/api/_index.md | 1 + content/api/howto.md | 5 +- content/api/service-tokens.md | 123 ++++++++++++++++++++++++++++++++++ 3 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 content/api/service-tokens.md diff --git a/content/api/_index.md b/content/api/_index.md index 536c1fb56..0581a2c1c 100644 --- a/content/api/_index.md +++ b/content/api/_index.md @@ -27,6 +27,7 @@ aliases: {{< cards >}} {{< card link="/developers/api/howto" title="How to use our API" subtitle="Learn more about Clever Cloud API, endpoints, auth and how to access it from multiple tools." icon="api" >}} + {{< card link="/developers/api/service-tokens" title="Service tokens" subtitle="Machine-to-machine credentials for your CI/CD pipelines, monitoring tools and scripts." icon="creds" >}} {{< card link="/developers/api/v2" title="Base v2 Endpoints" subtitle="Our base API endpoints with users, organisations, applications, add-ons, etc." icon="endpoints" >}} {{< card link="/developers/api/v4" title="New v4 Endpoints" subtitle="More recent API endpoints with billing, deployments, load balancers, logs, etc." icon="new" >}} diff --git a/content/api/howto.md b/content/api/howto.md index 99c6b544f..0015fdaf4 100644 --- a/content/api/howto.md +++ b/content/api/howto.md @@ -16,16 +16,19 @@ keywords: The [Clever Cloud Console](https://console.clever-cloud.com) and [Clever Tools](https://github.com/CleverCloud/clever-tools) allow you to manage your account and products with the same public API you can use for your own services and integrations. This article will explain how to connect to this API and use it. {{< cards >}} + {{< card link="/developers/api/service-tokens/" title="Service tokens" subtitle="Machine-to-machine credentials for your CI/CD pipelines, monitoring tools and scripts." icon="creds" >}} {{< card link="/developers/api/v2/" title="Base v2 Endpoints" subtitle="Our base API endpoints with users, organisations, applications, add-ons, etc." icon="endpoints" >}} {{< card link="/developers/api/v4/" title="New v4 Endpoints" subtitle="More recent API endpoints with billing, deployments, load balancers, logs, etc." icon="new" >}} {{< /cards >}} ## Request the API -Clever Cloud's REST API offers two authentication mechanisms to meet different integration needs: +Clever Cloud's REST API offers three authentication mechanisms to meet different integration needs: * **API tokens** provide a straightforward way to authenticate requests on behalf of a specific user. These tokens operate similarly to passwords and should be handled with appropriate security measures. API tokens are ideal for personal scripts, CLI tools, and scenarios where you're accessing your own resources. Use them to request the API Bridge: https://api-bridge.clever-cloud.com +* **Service tokens** are machine-to-machine credentials scoped to an organisation. They're based on [Biscuit](https://www.biscuitsec.org/) and carry their own role, so automated systems such as CI/CD pipelines, monitoring tools or scripts keep working without depending on a personal user account. Read [the service tokens documentation](/developers/api/service-tokens/) to create and use them. + * **OAuth 1** is designed for third-party applications that need to access Clever Cloud resources on behalf of their users. This authentication flow allows applications to request permissions from users without requiring direct access to their credentials. OAuth 1 is recommended for public applications, services that integrate with multiple user accounts, or any scenario where user delegation is required. Choose the authentication method that best aligns with your specific integration requirements and security considerations. diff --git a/content/api/service-tokens.md b/content/api/service-tokens.md new file mode 100644 index 000000000..88d9f98c8 --- /dev/null +++ b/content/api/service-tokens.md @@ -0,0 +1,123 @@ +--- +type: docs +weight: 2 +linkTitle: Service tokens +title: Service tokens +description: Create and use Clever Cloud organisation service tokens, machine-to-machine credentials for CI/CD pipelines, monitoring tools and scripts. +keywords: +- service tokens +- biscuit +- machine to machine +- automation +- ci/cd +- api +--- + +Organisation service tokens are machine-to-machine credentials based on [Biscuit](https://www.biscuitsec.org/). They allow automated systems such as CI/CD pipelines, monitoring tools or deployment scripts to interact with the Clever Cloud API without tying access to a personal user account. + +Unlike [API tokens](/developers/api/howto/#api-tokens), which authenticate requests on behalf of a specific user, a service token belongs to an organisation and carries its own role. Access no longer disappears when a team member leaves, and each automated system gets its own revocable credential, scoped to what it actually needs. + +## Scope and limitations + +A service token grants access to a single organisation. A token created for organisation A can't read or modify anything in organisation B, whatever role it carries. + +Service tokens are only implemented under `/v2/organisations/{id}` paths. Endpoints outside this prefix reject them, so `GET /v2/organisations` returns an error even with a valid token: always target the organisation the token belongs to. + +## Manage service tokens + +Manage service tokens through four endpoints under `/v2/organisations/{id}/service-tokens`: + +| Method | Path | Description | +| --- | --- | --- | +| `POST` | `/v2/organisations/{id}/service-tokens` | Create a token | +| `GET` | `/v2/organisations/{id}/service-tokens` | List tokens, supports `?limit=` and `?offset=` | +| `GET` | `/v2/organisations/{id}/service-tokens/{tokenId}` | Get a token | +| `DELETE` | `/v2/organisations/{id}/service-tokens/{tokenId}` | Revoke a token | + +These endpoints require your own credentials: create and revoke service tokens with the authentication method you already use, such as [`clever curl`](/developers/api/howto/#clever-curl), an API token through the API bridge, or OAuth 1. + +### Create a token + +Create a service token with a name, a role, an optional application scope and an optional lifetime: + +```bash +clever curl -X POST https://api.clever-cloud.com/v2/organisations//service-tokens \ + -H "Content-Type: application/json" \ + -d '{ + "name": "ci-deploy-token", + "role": "DEVELOPER", + "app_id": "app_xxx", + "ttl_seconds": 2592000 + }' +``` + +| Field | Required | Description | +| --- | --- | --- | +| `name` | Yes | Name identifying the token in the organisation | +| `role` | Yes | One of `ADMIN`, `MANAGER`, `DEVELOPER`, `ACCOUNTING` | +| `app_id` | No | Restricts the token to a single application or add-on | +| `ttl_seconds` | No | Token lifetime, from 1 second to 1 year. Defaults to 90 days | + +You can only assign a role equal to or lower than your own, so only organisation admins create `ADMIN` or `ACCOUNTING` tokens. Refer to [roles and privileges](/developers/doc/account/organisations/#roles-and-privileges) to pick the role matching what your automated system needs. + +Setting `app_id` restricts the token to a single application or add-on: the API rejects any request targeting another resource. Omit it to give the token organisation-wide access for its role. + +### List and revoke tokens + +List the tokens of an organisation, paginating with `limit` and `offset`: + +```bash +clever curl "https://api.clever-cloud.com/v2/organisations//service-tokens?limit=20&offset=0" +``` + +Deleting a token revokes it immediately, and the API rejects every subsequent request using it: + +```bash +clever curl -X DELETE https://api.clever-cloud.com/v2/organisations//service-tokens/ +``` + +## Authenticate with a service token + +Send the biscuit as a bearer token in the `Authorization` header: + +```bash +curl https://api.clever-cloud.com/v2/organisations//applications \ + -H "Authorization: Bearer " +``` + +### Deploy over HTTP + +Service tokens also work for `git push` over HTTP, which makes them convenient for CI/CD pipelines where no SSH key is available. Git uses Basic authentication here, and the biscuit goes in the username field, with an unused password: + +```text +Authorization: Basic base64(:) +``` + +Get the HTTP deployment URL of your application from the Clever Cloud Console, in **Information** > **Deployment URL**, then pass the token inline in the remote URL: + +```bash +git remote add clever https://@/.git +git push clever main +``` + +Writing the token in the remote URL stores it in `.git/config` and exposes it in process listings. To keep it out of both, provide it through `GIT_ASKPASS` instead: + +```bash +cat > /tmp/askpass.sh <<'EOF' +#!/bin/sh +echo "$SERVICE_TOKEN" +EOF +chmod +x /tmp/askpass.sh + +GIT_ASKPASS=/tmp/askpass.sh SERVICE_TOKEN="" \ + git push https:///.git main +``` + +## Security boundaries + +Service tokens enforce the same permission model as user roles, plus additional scoping. Each token belongs to one organisation, optionally to one application or add-on, and its role determines which operations it can perform: an `ACCOUNTING` token can't read application details, for example. + +Tokens are also time-limited and revocable. Once their lifetime has elapsed, the API rejects them. Deleting a token revokes it immediately, so rotating a compromised credential takes a single `DELETE` request. The audit trail records every request authenticated with a biscuit, which lets you trace what each automated system did. + +> [!WARNING] +> A service token is a credential granting access to your organisation's resources. Store it in the secret manager of your CI/CD platform, never in your repository, and give each automated system its own token with the narrowest role and application scope it can work with. From c6ebcbc04e3d43fb2c524a8753e645f77ca05480 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Brunat?= Date: Tue, 25 Aug 2026 10:38:38 +0200 Subject: [PATCH 2/3] api(service-tokens): map the ACCOUNTING role to its console label --- content/api/service-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/api/service-tokens.md b/content/api/service-tokens.md index 88d9f98c8..b3e4e47e6 100644 --- a/content/api/service-tokens.md +++ b/content/api/service-tokens.md @@ -58,7 +58,7 @@ clever curl -X POST https://api.clever-cloud.com/v2/organisations/ Date: Tue, 25 Aug 2026 11:14:43 +0200 Subject: [PATCH 3/3] api(service-tokens): align fields on the CLI implementation Replace app_id with the resources array, add the description field, and document the creation response along with the fact that the biscuit is only returned once, following the clever service-tokens implementation. Add a hidden note listing what to confirm before publishing: the token-api backend answering 502, and the CLI command set still being an unreleased draft PR. --- content/api/service-tokens.md | 41 ++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/content/api/service-tokens.md b/content/api/service-tokens.md index b3e4e47e6..41aa2246e 100644 --- a/content/api/service-tokens.md +++ b/content/api/service-tokens.md @@ -13,6 +13,20 @@ keywords: - api --- + + Organisation service tokens are machine-to-machine credentials based on [Biscuit](https://www.biscuitsec.org/). They allow automated systems such as CI/CD pipelines, monitoring tools or deployment scripts to interact with the Clever Cloud API without tying access to a personal user account. Unlike [API tokens](/developers/api/howto/#api-tokens), which authenticate requests on behalf of a specific user, a service token belongs to an organisation and carries its own role. Access no longer disappears when a team member leaves, and each automated system gets its own revocable credential, scoped to what it actually needs. @@ -45,8 +59,9 @@ clever curl -X POST https://api.clever-cloud.com/v2/organisations/", + "metadata": { + "id": "token_1a2b3c4d-5e6f-7890-abcd-ef1234567890", + "expiredAt": "2026-11-23T09:00:00Z" + } +} +``` + +> [!WARNING] +> The `token` field is only returned when you create the token. Store it in your secret manager right away: reading the token later returns its metadata, never the biscuit itself. + You can only assign a role equal to or lower than your own, so only organisation admins create `ADMIN` or `ACCOUNTING` tokens. Refer to [roles and privileges](/developers/doc/account/organisations/#roles-and-privileges) to pick the role matching what your automated system needs, where the `ACCOUNTING` role appears as **Accountant**. -Setting `app_id` restricts the token to a single application or add-on: the API rejects any request targeting another resource. Omit it to give the token organisation-wide access for its role. +Setting `resources` restricts the token to the listed applications or add-ons: the API rejects any request targeting another resource. Omit it to give the token organisation-wide access for its role. ### List and revoke tokens -List the tokens of an organisation, paginating with `limit` and `offset`: +Listing an organisation's tokens returns their metadata: identifier, name, status, creation date and expiration date. Paginate with `limit` and `offset`: ```bash clever curl "https://api.clever-cloud.com/v2/organisations//service-tokens?limit=20&offset=0" @@ -115,7 +146,7 @@ GIT_ASKPASS=/tmp/askpass.sh SERVICE_TOKEN="" \ ## Security boundaries -Service tokens enforce the same permission model as user roles, plus additional scoping. Each token belongs to one organisation, optionally to one application or add-on, and its role determines which operations it can perform: an `ACCOUNTING` token can't read application details, for example. +Service tokens enforce the same permission model as user roles, plus additional scoping. Each token belongs to one organisation, optionally to a restricted set of applications or add-ons, and its role determines which operations it can perform: an `ACCOUNTING` token can't read application details, for example. Tokens are also time-limited and revocable. Once their lifetime has elapsed, the API rejects them. Deleting a token revokes it immediately, so rotating a compromised credential takes a single `DELETE` request. The audit trail records every request authenticated with a biscuit, which lets you trace what each automated system did.