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]>
2026-10-18 05:52:51 +00:00 · 2026-01-29 08:38:36 -08:00
parent 7b6395c348
commit d8ea041c56
2826 changed files with 78739 additions and 23571 deletions
@@ -0,0 +1,244 @@
+---
+title: ZITADEL with Go
+sidebar_label: Go
+---
+
+This integration guide shows you how to integrate **ZITADEL** into your Go API. It demonstrates how to secure your API using
+OAuth 2 Token Introspection.
+
+> ℹ️ These examples and guides are based on our official [Go SDK](https://github.com/zitadel/zitadel-go).
+>
+> The SDK is a convenient wrapper around our low-level [OIDC library](https://github.com/zitadel/oidc). For most use cases, using the helpers provided in our [Go SDK](https://github.com/zitadel/zitadel-go) is the recommended approach for implementing authentication.
+
+At the end of the guide you should have an API with a protected endpoint.
+
+> This documentation references our HTTP example. There's also one for GRPC. Check them out on [GitHub](https://github.com/zitadel/zitadel-go/blob/next/example/api/http/main.go).
+
+## Prerequisites
+
+This will handle the OAuth 2.0 introspection request including authentication using JWT with Private Key using our [Go SDK](https://github.com/zitadel/zitadel-go).
+All that is required, is to create your API, create a private key and a personal access token for a service user.
+
+### Set up application and obtain keys
+
+Before we begin developing our API, we need to perform a few configuration steps in the ZITADEL Console.
+You'll need to provide some information about your app. We recommend creating a new app to start from scratch.
+
+Starting from the homepage of your management console, click on Create Application
+
+![](../../../public/img/go/api-create_application.png)
+
+Select a project from the dropdown and select *Other* as framework, then continue.
+
+![](../../../public/img/go/api-select_framework.png)
+
+Add your app name and select *API* as application type, then continue.
+
+![](../../../public/img/go/api-app_details.png)
+
+We recommend that you use JWT Profile for authenticating at the Introspection Endpoint. So select *JWT* as authentication method
+
+![](../../../public/img/go/api-select_jwt.png)
+
+You then need to create a new JSON key.
+
+![](../../../public/img/go/api-new_key.png)
+
+Select an expiration date that suits you.
+
+![](../../../public/img/go/api-expiration_date.png)
+
+And make sure to download it, as you won't be able to retrieve it again.
+
+![](../../../public/img/go/api-download_key.png)
+
+Now we need to create a *Personal Access Token* to authenticate the client requests.
+
+On the user view, switch to *Service Users* and create a new one.
+
+![](../../../public/img/go/api-service_user_panel.png)
+
+Give the service user a name and a user name. Select `Bearer` as *Access Token Type*.
+
+![](../../../public/img/go/api-create_service_user.png)
+
+### Create service user and personal access token (PAT)
+
+Once done, from the left panel of the user management, click on Personal Access Token and create a new one.
+
+![](../../../public/img/go/api-PAT_view.png)
+
+Set an expiration date and then copy the PAT generated to somewhere safe. We will need it later.
+
+![](../../../public/img/go/api-PAT_creation.png)
+
+## Go Setup
+
+### Add Go SDK to your project
+
+You need to add the [SDK](https://github.com/zitadel/zitadel-go) into Go Modules by:
+
+```bash
+go get -u github.com/zitadel/zitadel-go/v3
+```
+
+### Create example API
+
+Create a new go file with the content below. This will create an API with three endpoints:
+- `/api/healthz`: can be called by anyone and always returns `OK`
+- `/api/tasks`: requires authorization and returns the available tasks
+- `/api/add-task`: requires authorization with granted `admin` role and adds the task to the list
+
+If authorization is required, the token must not be expired and the API has to be part of the audience (either client_id or project_id).
+
+For tests we will use a Personal Access Token.
+
+```go reference
+https://github.com/zitadel/zitadel-go/blob/next/example/api/http/main.go
+```
+
+You will need to provide some values for the program to run:
+- `domain`: Your ZITADEL Custom Domain, e.g. https://my-domain.zitadel.cloud
+- `key`: The path to the downloaded key.json
+- `port`: The port on which the API will be accessible, default it 8089
+
+## Test API
+
+After you have configured everything correctly, you can simply start the example by:
+
+```bash
+go run main.go --domain <custom domain> --key <path>
+```
+
+This could look like:
+
+```bash
+go run main.go --domain my-domain.zitadel.cloud --key ./api.json
+```
+
+After you get a successful log:
+```
+2023/12/04 10:27:42 INFO server listening, press ctrl+c to stop addr=http://localhost:8089
+```
+
+### Public endpoint
+
+Now you can call the API by browser or curl. Try the healthz endpoint first:
+
+```bash
+curl -i http://localhost:8089/api/healthz
+```
+
+it should return something like:
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+Date: Mon, 04 Dec 2023 09:29:38 GMT
+Content-Length: 4
+
+"OK"
+```
+
+### Task list
+
+and the task list endpoint:
+
+```bash
+curl -i http://localhost:8089/api/tasks
+```
+
+it will return:
+
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: text/plain; charset=utf-8
+X-Content-Type-Options: nosniff
+Date: Mon, 04 Dec 2023 09:41:54 GMT
+Content-Length: 44
+
+unauthorized: authorization header is empty
+```
+
+We need to use the personal access token generated previously.
+
+If you provide a valid Bearer Token:
+
+```bash
+curl -i -H "Authorization: Bearer ${token}" http://localhost:8089/api/tasks
+```
+
+it will return an empty list:
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+Date: Mon, 04 Dec 2023 09:49:06 GMT
+Content-Length: 2
+
+{}
+```
+
+### Try to add a new task
+
+Let's see what happens if you call the AddTask endpoint:
+
+```bash
+curl -i -H "Authorization: Bearer ${token}" http://localhost:8089/api/add-task
+```
+
+it will complain about the missing `admin` role:
+```
+HTTP/1.1 403 Forbidden
+Content-Type: text/plain; charset=utf-8
+X-Content-Type-Options: nosniff
+Date: Mon, 04 Dec 2023 09:52:00 GMT
+Content-Length: 50
+
+permission denied: missing required role: `admin`
+```
+
+### Add administrator role
+
+So let's create the role and grant it to the user. To do so, go to your project in ZITADEL Management Console
+and create the role by selecting `Roles` in the navigation and then clicking on the `New Role` button.
+Finally, create the role as shown below:
+
+![Create project role in management console](../../../public/img/go/api-project-role.png)
+
+After you have created the role, let's grant it the user, who requested the tasks.
+Click on `Authorization` in the navigation and create a new one by selecting the user and the `admin` role.
+After successful creation, it should look like:
+
+![Created authorization in management console](../../../public/img/go/api-project-auth.png)
+
+So you should now be able to add a new task:
+
+```bash
+curl -i -H "Authorization: Bearer ${token}" http://localhost:8089/api/add-task --data "task=My new task"
+```
+
+which will report back the successful addition:
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+Date: Mon, 04 Dec 2023 10:06:29 GMT
+Content-Length: 26
+
+"task `My new task` added"
+```
+
+Let's now retrieve the task list again:
+
+```bash
+curl -i -H "Authorization: Bearer ${token}" http://localhost:8089/api/tasks
+```
+
+As you can see your new task ist listed. And since you're an `admin` now, you will always get an additional `create a new task on /api/add-task`:
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+Date: Mon, 04 Dec 2023 10:08:38 GMT
+Content-Length: 62
+
+{"tasks":["My new task","create a new task on /api/add-task"]}
+```