{"id":22009710,"url":"https://github.com/zitadel/zitadel-go","last_synced_at":"2026-01-16T20:27:49.206Z","repository":{"id":38363001,"uuid":"357159040","full_name":"zitadel/zitadel-go","owner":"zitadel","description":"ZITADEL Go - The official client library of ZITADEL for an easy integration into your Go project.","archived":false,"fork":false,"pushed_at":"2025-03-29T06:01:18.000Z","size":15276,"stargazers_count":91,"open_issues_count":19,"forks_count":34,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T07:19:06.634Z","etag":null,"topics":["go","zitadel","zitadel-sdk"],"latest_commit_sha":null,"homepage":"https://zitadel.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zitadel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-12T10:58:32.000Z","updated_at":"2025-03-28T10:29:17.000Z","dependencies_parsed_at":"2023-07-13T03:34:35.271Z","dependency_job_id":"20a0b930-7dcf-4e9b-8b62-3a00140c5bce","html_url":"https://github.com/zitadel/zitadel-go","commit_stats":null,"previous_names":["caos/zitadel-go"],"tags_count":113,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fzitadel-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fzitadel-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fzitadel-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Fzitadel-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zitadel","download_url":"https://codeload.github.com/zitadel/zitadel-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339145,"owners_count":20923012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","zitadel","zitadel-sdk"],"created_at":"2024-11-30T02:10:32.542Z","updated_at":"2026-01-05T14:24:12.634Z","avatar_url":"https://github.com/zitadel.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go SDK for Zitadel\n\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![Release](https://github.com/zitadel/zitadel-go/workflows/Release/badge.svg)](https://github.com/zitadel/zitadel-go/actions)\n[![license](https://badgen.net/github/license/zitadel/zitadel-go/)](https://github.com/zitadel/zitadel-go/blob/main/LICENSE)\n[![release](https://badgen.net/github/release/zitadel/zitadel-go/stable)](https://github.com/zitadel/zitadel-go/releases)\n[![tag](https://badgen.net/github/tag/zitadel/zitadel-go)](https://github.com/zitadel/zitadel-go/tags)\n[![Go Report Card](https://goreportcard.com/badge/github.com/zitadel/zitadel-go)](https://goreportcard.com/report/github.com/zitadel/zitadel-go)\n[![codecov](https://codecov.io/gh/zitadel/zitadel-go/branch/main/graph/badge.svg)](https://codecov.io/gh/zitadel/zitadel-go)\n\nThis is the Zitadel Go SDK, designed to provide a convenient and idiomatic way to interact with the Zitadel APIs in Go. The SDK provides a seamless wrapping of the Zitadel API, making it easy to authenticate service users and perform API operations.\n\nThe SDK enables efficient integration with the Zitadel API, allowing you to manage resources and execute actions.\n\nAdditionally, zitadel-go includes a powerful set of Authentication Helpers designed to secure your own Go web applications. This part of the SDK provides convenient HTTP middleware and wrappers that abstract away the complexities of OIDC, making it simple to add an \"Login with Zitadel\" flow, manage user sessions, and handle callbacks.\n\nThese helpers are built as a convenient wrapper around our powerful, low-level [zitadel/oidc](https://github.com/zitadel/oidc) library. For most developers looking to add user login to a Go web application, using these helpers is the recommended approach and should be sufficient.\n\n## Features\n\n- Authentication\n- Authorization checks\n- Client for Zitadel API\n\n## Usage\n\nAdd the package to your `go.mod` by\n\n```bash\ngo get -u github.com/zitadel/zitadel-go/v3\n```\n...and check out the [examples](./example) in this repo or head over to\nour [docs website](https://zitadel.com/docs/guides/start/quickstart#introduction).\n\n### Implementing Authentication\n\nWhen adding user authentication to your Go web application, we recommend using the helpers provided directly in this SDK. These helpers are a convenient, high-level wrapper around our powerful, low-level `zitadel/oidc` library and are designed to handle most common use cases, like login flows and session management, right out of the box.\n\nSince we are actively expanding our formal documentation for this feature, the best way to get started is by exploring the working examples we've provided in this repository.\n\n**Web Application Example**\n\n[This example](./example/app) demonstrates how to add a complete OIDC login flow to a standard Go web application. It includes:\n\n-   A home page with a login button.\n-   User authentication using the OIDC PKCE Flow.\n-   A public page accessible without login.\n-   A private page showing user info after login.\n-   A logout function.\n\n**API Application Example**\n\n[This example](./example/api) shows how to secure a REST API, where different endpoints require a valid ZITADEL token for access. It includes:\n\n-   A public endpoint accessible without a token.\n-   A private endpoint accessible with any valid token.\n-   An administrator endpoint accessible only by users with a specific role.\n\n---\n\n### Accessing APIs\n\nThe SDK offers [three ways to authenticate with Zitadel](https://zitadel.com/docs/apis/openidoauth/authn-methods). Each method has its\nown benefits—choose the one that fits your situation best.\n\n#### 1. Private Key JWT Authentication\n\n**What is it?**\nYou use a JSON Web Token (JWT) that you sign with a private key stored in a\nJSON file. This process creates a secure token.\n\nhttps://zitadel.com/docs/apis/openidoauth/endpoints#jwt-profile-grant\n\n**When should you use it?**\n\n- **Best for production:** It offers strong security.\n- **Advanced control:** You can adjust token settings like expiration.\n\n**How do you use it?**\n\n1. Save your private key in a JSON file.\n2. Build the client\n\n**Example:**\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"os\"\n\t\"log/slog\"\n\n\t\"github.com/zitadel/oidc/v3/pkg/oidc\"\n\n\t\"github.com/zitadel/zitadel-go/v3/pkg/client\"\n\t\"github.com/zitadel/zitadel-go/v3/pkg/client/zitadel/management\"\n\t\"github.com/zitadel/zitadel-go/v3/pkg/zitadel\"\n)\n\nfunc main() {\n\tdomain := \"https://example.us1.zitadel.cloud\"\n\tkeyPath := \"path/to/jwt-key.json\"\n\n\tctx := context.Background()\n\n\tauthOption := client.DefaultServiceUserAuthentication(\n\t\tkeyPath,\n\t\toidc.ScopeOpenID,\n\t\tclient.ScopeZitadelAPI(),\n\t)\n\n\tapi, err := client.New(ctx, zitadel.New(domain), client.WithAuth(authOption))\n\tif err != nil {\n\t\tslog.Error(\"could not create api client\", \"error\", err)\n\t\tos.Exit(1)\n\t}\n\n\tresp, err := api.ManagementService().GetMyOrg(ctx, \u0026management.GetMyOrgRequest{})\n\tif err != nil {\n\t\tslog.Error(\"gRPC call failed\", \"error\", err)\n\t\tos.Exit(1)\n\t}\n\n\tlog.Printf(\"Successfully called API: Your organization is %s\", resp.GetOrg().GetName())\n}\n```\n\n#### 2. Client Credentials Grant\n\n**What is it?**\nThis method uses a client ID and client secret to get a secure access token,\nwhich is then used to authenticate.\n\nhttps://zitadel.com/docs/apis/openidoauth/endpoints#client-credentials-grant\n\n**When should you use it?**\n\n- **Simple and straightforward:** Good for server-to-server communication.\n- **Trusted environments:** Use it when both servers are owned or trusted.\n\n**How do you use it?**\n\n1. Provide your client ID and client secret.\n2. Build the client\n\n**Example:**\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"os\"\n\t\"log/slog\"\n\n\t\"github.com/zitadel/oidc/v3/pkg/oidc\"\n\n\t\"github.com/zitadel/zitadel-go/v3/pkg/client\"\n\t\"github.com/zitadel/zitadel-go/v3/pkg/client/zitadel/management\"\n\t\"github.com/zitadel/zitadel-go/v3/pkg/zitadel\"\n)\n\nfunc main() {\n\tdomain := \"https://example.us1.zitadel.cloud\"\n\tclientID := \"id\"\n\tclientSecret := \"secret\"\n\n\tctx := context.Background()\n\n\tauthOption := client.PasswordAuthentication(\n\t\tclientID,\n\t\tclientSecret,\n\t\toidc.ScopeOpenID,\n\t\tclient.ScopeZitadelAPI(),\n\t)\n\n\tapi, err := client.New(ctx, zitadel.New(domain), client.WithAuth(authOption))\n\tif err != nil {\n\t\tslog.Error(\"could not create api client\", \"error\", err)\n\t\tos.Exit(1)\n\t}\n\n\tresp, err := api.ManagementService().GetMyOrg(ctx, \u0026management.GetMyOrgRequest{})\n\tif err != nil {\n\t\tslog.Error(\"gRPC call failed\", \"error\", err)\n\t\tos.Exit(1)\n\t}\n\n\tlog.Printf(\"Successfully called API: Your organization is %s\", resp.GetOrg().GetName())\n}\n```\n\n#### 3. Personal Access Tokens (PATs)\n\n**What is it?**\nA Personal Access Token (PAT) is a pre-generated token that you can use to\nauthenticate without exchanging credentials every time.\n\n**When should you use it?**\n\n- **Easy to use:** Great for development or testing scenarios.\n- **Quick setup:** No need for dynamic token generation.\n\n**How do you use it?**\n\n1. Obtain a valid personal access token from your account.\n2. Build the client\n\n**Example:**\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"os\"\n\t\"log/slog\"\n\n\t\"github.com/zitadel/zitadel-go/v3/pkg/client\"\n\t\"github.com/zitadel/zitadel-go/v3/pkg/client/zitadel/management\"\n\t\"github.com/zitadel/zitadel-go/v3/pkg/zitadel\"\n)\n\nfunc main() {\n\tdomain := \"https://example.us1.zitadel.cloud\"\n\ttoken := \"token\"\n\n\tctx := context.Background()\n\n\tauthOption := client.PAT(token)\n\n\tapi, err := client.New(ctx, zitadel.New(domain), client.WithAuth(authOption))\n\tif err != nil {\n\t\tslog.Error(\"could not create api client\", \"error\", err)\n\t\tos.Exit(1)\n\t}\n\n\tresp, err := api.ManagementService().GetMyOrg(ctx, \u0026management.GetMyOrgRequest{})\n\tif err != nil {\n\t\tslog.Error(\"gRPC call failed\", \"error\", err)\n\t\tos.Exit(1)\n\t}\n\n\tlog.Printf(\"Successfully called API: Your organization is %s\", resp.GetOrg().GetName())\n}\n```\n\n---\n\nChoose the authentication method that best suits your needs based on your\nenvironment and security requirements. For more details, please refer to the\n[Zitadel documentation on authenticating service users](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users).\n\n### Versions\n\nIf you're looking for older version of this module, please check out the following tags:\n\n- v3.x.x is maintained on the [main](https://github.com/zitadel/zitadel-go/tree/main) branch\n- [v2.2.8](https://github.com/zitadel/zitadel-go/releases/tag/v2.2.8) is the last release for the v2 Go module\n- [v0.3.5](https://github.com/zitadel/zitadel-go/releases/tag/v0.3.5) is the last release for the v0/v1 Go module\n\nCurrently only v3 is supported, due to some security updates that involve breaking changes. Therefore v2 and older will\nno longer be supported.\n\n## Supported Go Versions\n\nFor security reasons, we only support and recommend the use of one of the latest two Go versions (:white_check_mark:).\nVersions that also build are marked with :warning:.\n\n| Version | Supported          |\n|---------|--------------------|\n| \u003c1.24   | :x:                |\n| 1.24    | :white_check_mark: |\n| 1.25    | :white_check_mark: |\n\n## License\n\nThe full functionality of this library is and stays open source and free to use for everyone. Visit\nour [website](https://zitadel.com) and get in touch.\n\nSee the exact licensing terms [here](./LICENSE)\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"\nAS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific\nlanguage governing permissions and limitations under the License.\n\n## Contributors\n\n\u003ca href=\"https://github.com/zitadel/zitadel-go/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=zitadel/zitadel-go\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzitadel%2Fzitadel-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzitadel%2Fzitadel-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzitadel%2Fzitadel-go/lists"}