feat: support organization-scoped API tokens

docs/api/index.md

@@ -9,7 +9,37 @@ The API of the OpenCVE Cloud instance is available on [https://app.opencve.io/ap
 
 ## Authentication
 
-We only support basic authentication for now, but we plan to add other ones like token based authentication.
+The OpenCVE API supports two authentication methods: **Organization API Tokens** and **Basic Authentication (legacy)**.
+
+### Organization API Tokens (recommendend)
+
+Organization API tokens provide a secure way to authenticate API requests without relying on user credentials. They are designed for automation and machine-to-machine access, such as scripts, CI/CD pipelines, or SIEM integrations.
+
+Each organization can create multiple tokens and revoke them at any time. If a token is compromised, it can be revoked without impacting user accounts or other tokens.
+
+Tokens use the Bearer authentication scheme and must be sent in the `Authorization` header:
+
+```
+Authorization: Bearer opc_org.<token_id>.<secret>
+```
+
+For example with `curl`:
+
+```
+curl https://app.opencve.io/api/cve \
+  -H "Authorization: Bearer opc_org.pCTcwAFEAY8y.qgavaGPuu8ZbitbN5MKk9T0diuwLW6rc" \
+  -H "Accept: application/json"
+```
+
+Organization API tokens can be created from the organization settings page. For security reasons, the token secret is displayed **only once** at creation time. Make sure to copy and store it securely.
+
+![API Organization Token](../images/api_org_token.png){.center style="width:90%"}
+
+### Basic Authentication (legacy)
+
+Basic Authentication is still supported for backward compatibility but will be **deprecated in the future**.
+
+This authentication method requires sending user credentials with each request and does not allow credential rotation or revocation without impacting the user account. For these reasons, we strongly recommend using organization API tokens instead.
 
 To use the Basic Authentication with the OpenCVE API, simply pass your credentials in the `Authorization` header.
 
@@ -19,8 +49,6 @@ Most clients do it for you, for example using `curl` :
 curl -u username:password https://app.opencve.io/api/cve
 ```
 
-You can omit your password, curl will interactively ask you.
-
 ## Pagination
 
 Some endpoints can return lots of results (list the CVEs for instance). In these cases the request must be paginated with the `?page` parameter.