mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-29 10:32:15 +00:00
f4f43f5248
# Which Problems Are Solved Pages in `apps/docs` that embed source from GitHub via the Docusaurus convention ```` ```js reference https://github.com/zitadel/actions/blob/main/examples/org_metadata_claim.js ``` ```` stopped working after the migration from Docusaurus to fumadocs. The old `docusaurus-theme-github-codeblock` plugin used to fetch the file and render it; fumadocs has no support for that meta, so the page rendered the raw URL as plain code-block text. Visible at `/docs/apis/actions/code-examples` and 16 other pages. # How the Problems Are Solved - Converted every ```` ```<lang> reference\n<URL>\n``` ```` block (46 total across 17 `.mdx` files) to the native fumadocs JSX form: `<GithubCodeBlock url="<URL>" />`. The existing `<details>`/`<summary>` collapsibles around blocks are kept — they're an authoring choice, not part of the rendering bug. - Updated `apps/docs/components/github-code-block.tsx` to render via `DynamicCodeBlock` from `fumadocs-ui/components/dynamic-codeblock` (proper shiki highlighting) instead of raw `CodeBlock` + `Pre` (which produced unhighlighted output). Also fixed language detection so a URL hash like `#L10-L20` no longer pollutes the language token. - Registered `GithubCodeBlock` globally in `apps/docs/mdx-components.tsx`, matching how every other shared component (`APIPage`, `Callout`, `Tab/Tabs`, `Step/Steps`, `Admonition`, `TerminologyUpdate`) is exposed. MDX files no longer need a local `import`. # Additional Changes - Normalized the two MDX files that were already using the JSX form (`examples/secure-api/python-django.mdx`, `examples/secure-api/java-spring.mdx`): removed their now-redundant local `import { GithubCodeBlock }` and rewrote 9 long-form `<GithubCodeBlock url="..."></GithubCodeBlock>` tags to self-closing for consistency. # Additional Context Verified locally with `pnpm --filter @zitadel/docs dev`: - `/docs/apis/actions/code-examples` — 20 shiki-highlighted code blocks rendered inside the `<details>` collapsibles (was 0). - `/docs/apis/openidoauth/claims` — line-range hashes (`#L9-L11`) honored. - `/docs/examples/login/flutter` — mixed languages (xml/dart/html) detected and highlighted. - `/docs/guides/integrate/external-audit-log` — edge case of fenced reference indented inside a numbered list also converted and rendered. Greps: - `^[ \t]*\`\`\`[a-zA-Z0-9]+ reference` in `apps/docs/content/**/*.mdx` → 0 matches. - `<GithubCodeBlock url="` in `apps/docs/content/**/*.mdx` → 55 matches. - `from '@/components/github-code-block'` in `apps/docs/content/**/*.mdx` → 0 matches. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
86 lines
3.9 KiB
Plaintext
86 lines
3.9 KiB
Plaintext
---
|
||
title: Integrate ZITADEL APIs into a Go Application
|
||
description: "Example showing how to call ZITADEL Management APIs from a Go application using service account credentials."
|
||
sidebar_label: Example Go
|
||
---
|
||
|
||
This integration guide shows you how to integrate **ZITADEL** into your Go application.
|
||
It demonstrates how to fetch some data from the ZITADEL management API.
|
||
|
||
> ℹ️ 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 application able to read the details of your organization.
|
||
|
||
> This documentation references our [CLI example](https://github.com/zitadel/zitadel-go/blob/next/example/client/cli/cli.go).
|
||
|
||
## Prerequisites
|
||
|
||
The client [SDK](https://github.com/zitadel/zitadel-go) will handle all necessary OAuth 2.0 requests and send the required headers to the ZITADEL API using our [Go SDK](https://github.com/zitadel/zitadel-go).
|
||
All that is required, is a service account with an Org Owner (or another role, depending on the needed api requests) role assigned and its key JSON.
|
||
|
||
However, we recommend you read the guide on [how to access ZITADEL API](/guides/integrate/zitadel-apis/access-zitadel-apis)) and the associated guides for a basic knowledge of :
|
||
- [Recommended Authorization Flows](/guides/integrate/login/oidc/oauth-recommended-flows)
|
||
- [Service Accounts](/guides/integrate/service-accounts/authenticate-service-accounts)
|
||
|
||
> Be sure to have a valid key JSON and that its service account is either ORG_OWNER or at least ORG_OWNER_VIEWER before you continue with this guide.
|
||
|
||
## Go Setup
|
||
|
||
### Add Go SDK to your project
|
||
|
||
You need to add the SDK into Go Modules by:
|
||
|
||
```bash
|
||
go get -u github.com/zitadel/zitadel-go/v3
|
||
```
|
||
|
||
### Create example application
|
||
|
||
Create a new go file with the content below. This will create a application and call its `GetMyOrg` function on the ManagementService.
|
||
The SDK will make sure you will have access to the API by retrieving a Bearer Token using JWT Profile with the provided scopes (`openid` and `urn:zitadel:iam:org:project:id:zitadel:aud`).
|
||
|
||
<GithubCodeBlock url="https://github.com/zitadel/zitadel-go/blob/next/example/client/cli/cli.go" />
|
||
|
||
### Test
|
||
|
||
After you have configured everything correctly, you can simply start the example by:
|
||
|
||
```bash
|
||
go run cli.go --domain <custom domain> --key <path>
|
||
```
|
||
|
||
This could look like:
|
||
|
||
```bash
|
||
go run cli.go --domain my-domain.zitadel.cloud --key ./api.json
|
||
```
|
||
|
||
This will output something similar to:
|
||
|
||
```
|
||
2023/12/20 08:48:23 INFO retrieved the organisation orgID=165467338479501569 name=DemoOrg
|
||
```
|
||
|
||
## Completion
|
||
|
||
You have successfully used the ZITADEL Go SDK to call the management API!
|
||
|
||
If you encountered an error (e.g. `code = PermissionDenied desc = No matching permissions found`),
|
||
ensure your service account has the required permissions by assigning the `ORG_OWNER` or `ORG_OWNER_VIEWER` role
|
||
and check the mentioned [guides](#prerequisites) at the beginning.
|
||
|
||
If you've run into any other problem, don't hesitate to contact us or raise an issue on [ZITADEL](https://github.com/zitadel/zitadel/issues) or in the [SDK](https://github.com/zitadel/zitadel-go/issues).
|
||
|
||
### Whats next?
|
||
|
||
Now you can proceed implementing our APIs by adding more calls or using a different service like the SessionService:
|
||
|
||
```go
|
||
api.SessionService().CreateSession(ctx, &session.CreateSessionRequest{})
|
||
```
|
||
Checkout more [examples from the SDK](https://github.com/zitadel/zitadel-go/blob/next/example),
|
||
like how you can integrate the [application in your own API](https://github.com/zitadel/zitadel-go/blob/next/example/api/client/main.go)
|
||
or refer to our [API Docs](/apis/introduction).
|