mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
Marco A.andGitHub
382aec2d61
# Which Problems Are Solved Inconsistent naming of service account, found in the following variations: - Machine User - machine user - Service User - Machine Account - Technical Account - User: Type Machine # How the Problems Are Solved Attentive search and replace. Localizations have been translated using Copilot # Additional Changes Some unused methods have been removed from the Go code. # Additional Context - Closes #11285
87 lines
3.7 KiB
Plaintext
87 lines
3.7 KiB
Plaintext
---
|
||
title: Integrate ZITADEL APIs into a Go Application
|
||
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`).
|
||
|
||
```go reference
|
||
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).
|