docs: introduce versioned docs and migrate to fuma (#11166)

## Todos for release

- [x] Configure Env in docs project on vercel
- [x] Configure Root Path in the docs project on vercel
- [ ] Remove old CSP https://github.com/zitadel/website/pull/1592

## What we did

This pull request migrates the project documentation from the old
`docs/` directory to the new `apps/docs/` directory, introduces a new
documentation system built with Next.js and Fumadocs, and updates all
relevant references, configuration files, and documentation to reflect
this change. It also adds new configuration and ignore files for the new
documentation app, updates CI and linting to exclude the new docs from
certain checks, and revises the contributing guidelines accordingly.

**Documentation System Migration and New Docs App**

* Migrated all documentation from `docs/` to `apps/docs/`, and updated
all references in `README.md`, `CONTRIBUTING.md`, and other files to
point to the new location.
[[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640)
[[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607)
[[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687)
[[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3)
[[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30)
* Added a new Next.js/Fumadocs-based documentation app under
`apps/docs/`, including core app files, layouts, routing, search API,
and a comprehensive `README.md` with development and contribution
instructions.
[[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74)
[[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39)
[[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7)
[apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81),
[apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79),
[[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7)
[[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29)
[[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25)

**Configuration and Tooling Updates**

* Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and
`.github/dependabot.yml` to properly handle the new docs app: excluded
`apps/docs` from certain checks, added npm dependency updates for the
docs app, and excluded generated content.
[[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14)
[[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6)
[[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129)
[[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106)
* Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3
version for consistency.

**Licensing and Miscellaneous**

* Added `apps/docs/` to the list of licensed directories in
`LICENSING.md`.

These changes ensure the documentation is now maintained in a modern,
scalable system and all project tooling is updated to support the new
structure.

---------

Co-authored-by: Federico Coppede <[email protected]>
This commit is contained in:
Florian Forster
2026-01-29 08:38:36 -08:00
committed by GitHub
co-authored by Federico Coppede
parent 7b6395c348
commit d8ea041c56
2826 changed files with 78739 additions and 23571 deletions
@@ -0,0 +1,20 @@
Upon successful introspection, regardless of the token type or introspection method, a response with the boolean `active` is returned, indicating if the provided token is active and if the requesting client is part of the token audience. If `active` is true, further information will be provided:
| **Property** | **Description** |
| --- | --- |
| `aud` | The audience of the token |
| `client_id` | The client_id of the application the token was issued to |
| `exp` | Time the token expires (as unix time) |
| `iat` | Time the token was issued at (as unix time) |
| `iss` | Issuer of the token |
| `jti` | Unique id of the token |
| `nbf` | Time the token must not be used before (as unix time) |
| `scope` | Space delimited list of scopes granted to the token |
| `token_type` | Type of the inspected token. Value is always Bearer |
| `username` | ZITADEL's login name of the user. Consists of username@primarydomain |
Depending on the granted scopes, additional information about the authorized user is provided.
If the authorization fails, an HTTP 401 with invalid_client will be returned.
In summary, the introspection endpoint plays a crucial role in validating access tokens, either opaque or JWT, ensuring that they are not revoked.
@@ -0,0 +1,103 @@
---
title: Basic Authentication in ZITADEL
sidebar_label: Basic Authentication
---
import IntrospectionResponse from './_introspection-response.mdx';
This is a guide on how to secure your API using [Basic Authentication](/apis/openidoauth/authn-methods#client-secret-basic).
## Register the API in ZITADEL
1. Go to your project and click on the **New** button as shown below.
<img
src="/docs/img/guides/integrate/token-introspection-basic-auth-1.png"
width="75%"
alt="Register the API"
/>
2. Give a name to your application (Test API 2 is the name given below) and select type **API**.
<img
src="/docs/img/guides/integrate/token-introspection-basic-auth-2.png"
width="75%"
alt="Register the API"
/>
3. Select **Basic** as the authentication method and click **Continue**.
<img
src="/docs/img/guides/integrate/token-introspection-basic-auth-3.png"
width="75%"
alt="Register the API"
/>
4. Now review your configuration and click **Create**.
<img
src="/docs/img/guides/integrate/token-introspection-basic-auth-4.png"
width="75%"
alt="Register the API"
/>
5. You will now see the API’s **Client ID** and the **Client Secret**. Copy them and click **Close**.
<img
src="/docs/img/guides/integrate/token-introspection-basic-auth-5.png"
width="75%"
alt="Register the API"
/>
6. When you click **URLs** on the left, you will see the relevant OIDC URLs. Note down the **issuer** URL, **token_endpoint** and **introspection_endpoint**.
<img
src="/docs/img/guides/integrate/token-introspection-basic-auth-6.png"
width="75%"
alt="Register the API"
/>
7. Also note down the **Resource ID** of your project.
<img
src="/docs/img/guides/integrate/token-introspection-basic-auth-7.png"
width="75%"
alt="Register the API"
/>
## Token introspection
With Basic Authentication, you will receive a Client ID and Client Secret for your API. Send your client_id and client_secret as a Basic Auth Header in the following format:
```
Authorization: "Basic " + base64( formUrlEncode(client_id) + ":" + formUrlEncode(client_secret) )
```
The request from the API to the introspection endpoint should be in the following format:
```bash
curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/introspect \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {your_basic_auth_header}' \
--data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn...
```
Here's an example of how this is done in Python code:
```python
def introspect_token(self, token_string):
url = ZITADEL_INTROSPECTION_URL
data = {'token': token_string, 'token_type_hint': 'access_token', 'scope': 'openid'}
auth = HTTPBasicAuth(API_CLIENT_ID, API_CLIENT_SECRET)
resp = requests.post(url, data=data, auth=auth)
resp.raise_for_status()
return resp.json()
```
## Introspection response
<IntrospectionResponse components={props.components} />
Follow this [tutorial](https://github.com/zitadel/examples-api-access-and-token-introspection/tree/main/api-basic-authentication) to learn how to register an API application using Basic Auth with ZITADEL and test it.
@@ -0,0 +1,38 @@
---
title: Token introspection
sidebar_label: Token introspection
---
import DocCardList from '@/components/docusaurus/doc-card-list';
Token introspection is the process of checking whether an access token is valid and can be used to access protected resources.
You have an API that acts as an OAuth resource server and can be accessed by user-facing applications.
To validate an access token by calling the ZITADEL introspection API, you can use the JSON Web Token (JWT) Profile (recommended) or Basic Authentication for token introspection.
It's crucial to understand that the API is entirely separate from the front end.
The API shouldn’t concern itself with the token type received.
Instead, it's about how the API chooses to call the introspection endpoint, either through JWT Profile or Basic Authentication.
Many APIs assume they might receive a JWT and attempt to verify it based on signature or expiration.
However, with ZITADEL, you can send either a JWT or an opaque Bearer token from the client end to the API.
This flexibility is one of ZITADEL's standout features.
## API application
If you have an API that behaves as an OAuth resource server that can be accessed by user-facing applications and need to validate an access token by calling the ZITADEL introspection API, you can use the following methods to register these APIs in ZITADEL:
- [JSON Web Token (JWT) Profile (Recommended)](/guides/integrate/token-introspection/private-key-jwt)
- [Basic Authentication](/guides/integrate/token-introspection/basic-auth)
## Service users
If there are client APIs or systems that need to access other protected APIs, these APIs or systems must be declared as [service users](/guides/manage/console/users-overview).
A service user is not considered an application type in ZITADEL.
Read the introduction on how to [authenticate service users](/guides/integrate/service-users/authenticate-service-users).
## Further references
- [Introspection API reference](/apis/openidoauth/endpoints#token-endpoint)
- [JWT vs. opaque tokens](/concepts/knowledge/opaque-tokens)
- [Python examples for securing an API and invoking it as a service user](https://github.com/zitadel/examples-api-access-and-token-introspection)
<DocCardList />
@@ -0,0 +1,200 @@
---
title: Private Key JWT
sidebar_label: Private Key JWT
---
import IntrospectionResponse from './_introspection-response.mdx';
This guide explains how to use ZITADEL's [Private Key JWT authentication method](/apis/openidoauth/authn-methods#jwt-with-private-key) to authenticate your application and call the token introspection endpoint. This is not about securing an API, but about allowing your backend to introspect access tokens in a secure way.
If you're looking to set up Private Key JWT authentication specifically for Service Users, see our dedicated guide [here](/guides/integrate/service-users/private-key-jwt).
## Register an Application & Generate a Key Pair
To use Private Key JWT for introspection, you must register your client application in ZITADEL and create a key pair. This process enables your application to obtain credentials needed to generate JWT assertions for authentication.
1. In your ZITADEL project, click **New** to add an application.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-1.png"
width="75%"
alt="Register the app"
/>
2. Enter a name (e.g., "Backend Client") and select **API** as the application type.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-2.png"
width="75%"
alt="Set application type"
/>
3. Choose **JWT** as the authentication method and click **Continue**.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-3.png"
width="75%"
alt="Choose JWT Profile"
/>
4. Review your settings and click **Create**.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-4.png"
width="75%"
alt="Create application"
/>
5. After creation, you’ll see the application’s **Client ID**. There is no client secret—instead, authentication relies on your private key and JWT.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-5.png"
width="75%"
alt="Client ID"
/>
6. To generate a key pair, click **New** under the application’s keys section.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-6.png"
width="75%"
alt="Generate a new key"
/>
7. Select **JSON** as the key type, set an expiration if desired, and click **Add**.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-7.png"
width="75%"
alt="Key details"
/>
8. Download and save the generated key by clicking **Download**. Afterward, click **Close**.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-8.png"
width="75%"
alt="Download key"
/>
9. The downloaded key file will look like this:
```
{
"type": "application",
"keyId": "<YOUR_KEY_ID>",
"key": "-----BEGIN RSA PRIVATE KEY-----\n<YOUR_PRIVATE_KEY>\n-----END RSA PRIVATE KEY-----\n",
"appId": "<YOUR_APP_ID>",
"clientId": "<YOUR_CLIENT_ID>"
}
```
10. In the left menu, select **URLs** to view the application’s OIDC endpoints. Note the **issuer** URL, **token_endpoint**, and **introspection_endpoint**.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-10.png"
width="75%"
alt="OIDC Endpoints"
/>
11. Optionally, note your **Resource ID** for reference.
<img
src="/docs/img/guides/integrate/token-introspection-jwt-profile-11.png"
width="75%"
alt="Resource ID"
/>
## Calling the Introspection Endpoint
To introspect an access token in ZITADEL, your backend must authenticate by providing a JWT (`client_assertion`) signed with your application's private key. ZITADEL verifies this JWT to ensure the request is from a trusted application.
**Required request parameters:**
| **Parameter** | **Description** |
|------------------------- |---------------------------------------------------------------------------------------------------------------------|
| `client_assertion` | The JWT assertion created and signed as described below. |
| `client_assertion_type` | Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |
| `token` | The access token you want to introspect. |
### Creating the Client Assertion (JWT)
The `client_assertion` parameter is a signed JWT with the following structure:
**Header:**
```json
{
"alg": "RS256",
"kid": "<YOUR_KEY_ID>"
}
```
**Payload:**
```json
{
"iss": "<YOUR_CLIENT_ID>",
"sub": "<YOUR_CLIENT_ID>",
"aud": "https://${YOUR_DOMAIN}", // Your ZITADEL issuer URL
"exp": 1605183582, // Expiry (Unix timestamp)
"iat": 1605179982 // Issued at (Unix timestamp, not older than 1 hour)
}
```
- `iss` and `sub`: Your application’s Client ID.
- `aud`: The issuer URL for your ZITADEL instance (e.g. `https://my-tenant.zitadel.cloud`).
- `exp`: JWT expiration time (seconds since epoch).
- `iat`: JWT issued at time (seconds since epoch), must not be older than 1 hour.
You can generate the signed JWT using libraries in your preferred language or helper tools like [zitadel-tools](https://github.com/zitadel/zitadel-tools) or [https://dinochiesa.github.io/jwt/](https://dinochiesa.github.io/jwt/).
### Example Introspection HTTP Request
Make a POST request to the introspection endpoint, sending the above parameters:
```bash
curl --request POST \
--url ${YOUR_DOMAIN}/oauth/v2/introspect \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
--data client_assertion=eyJhbGciOiJSUzI1Ni... \
--data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR
```
### Python Example
Below is a Python function that generates the JWT assertion and performs token introspection:
```python
def introspect_token(token_string):
# Build JWT for client assertion
payload = {
"iss": API_KEY_FILE["clientId"],
"sub": API_KEY_FILE["clientId"],
"aud": ZITADEL_ISSUER_URL,
"exp": int(time.time()) + 60 * 60, # expires in 1 hour
"iat": int(time.time())
}
headers = {
"alg": "RS256",
"kid": API_KEY_FILE["keyId"]
}
jwt_token = jwt.encode(payload, API_KEY_FILE["key"], algorithm="RS256", headers=headers)
req_headers = {"Content-Type": "application/x-www-form-urlencoded"}
req_data = {
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": jwt_token,
"token": token_string
}
response = requests.post(ZITADEL_INTROSPECTION_ENDPOINT, headers=req_headers, data=req_data)
response.raise_for_status()
token_data = response.json()
print(f"Token data from introspection: {token_data}")
return token_data
```
## Introspection Response
<IntrospectionResponse components={props.components} />
For more details and a complete working example, see this [tutorial](https://github.com/zitadel/examples-api-access-and-token-introspection/tree/main/api-jwt) on registering an application in ZITADEL and calling the introspection endpoint with a JWT assertion.