The WorkOS Go library provides a flat, root-level workos package for applications written in Go.
Requires Go 1.23+.
go get github.com/workos/workos-go/v7package main
import (
"context"
"log"
"github.com/workos/workos-go/v7"
)
func main() {
client := workos.NewClient(
"<WORKOS_API_KEY>",
workos.WithClientID("<WORKOS_CLIENT_ID>"),
)
organization, err := client.Organizations().Get(context.Background(), "org_123")
if err != nil {
log.Fatal(err)
}
_ = organization
}All API resources are accessed through service accessors on the Client:
| Accessor | Description |
|---|---|
APIKeys() |
Organization API key management |
AdminPortal() |
Admin Portal link generation |
AuditLogs() |
Audit log events and retention |
Authorization() |
Fine-grained authorization (FGA) and RBAC |
Connect() |
Connect application management |
DirectorySync() |
Directory Sync (directories, users, groups) |
Events() |
Event stream |
FeatureFlags() |
Feature flag management and evaluation |
MultiFactorAuth() |
Multi-factor authentication challenges |
OrganizationDomains() |
Organization domain verification |
Organizations() |
Organization CRUD |
Passwordless() |
Passwordless authentication sessions |
Pipes() |
Data integration pipes |
Radar() |
Radar list management |
SSO() |
Single Sign-On connections and profiles |
UserManagement() |
Users, invitations, auth methods |
Vault() |
Key-value storage and client-side encryption |
Webhooks() |
Webhook endpoint management |
Widgets() |
Widget token generation |
The SDK returns typed errors that can be inspected with errors.As, including the base *workos.APIError:
| Type | HTTP Status | Description |
|---|---|---|
AuthenticationError |
401 | Invalid or missing API key |
NotFoundError |
404 | Requested resource does not exist |
UnprocessableEntityError |
422 | Validation errors |
RateLimitExceededError |
429 | Rate limit exceeded (auto-retried) |
ServerError |
5xx | WorkOS server error (auto-retried) |
NetworkError |
- | Connection failure |
result, err := client.Organizations().Get(ctx, "org_123")
if err != nil {
var notFound *workos.NotFoundError
if errors.As(err, ¬Found) {
log.Printf("Organization not found: %s", notFound.Message)
}
}List endpoints return an Iterator[T] for auto-pagination:
iter := client.UserManagement().List(ctx, &workos.UserManagementListParams{})
for iter.Next() {
user := iter.Current()
fmt.Println(user.Email)
}
if err := iter.Err(); err != nil {
log.Fatal(err)
}Manage webhook endpoints with client.Webhooks(). Verify incoming webhook payloads with workos.NewWebhookVerifier(...):
v := workos.NewWebhookVerifier(secret)
payload, err := v.VerifyPayload(sigHeader, rawBody)
if err != nil {
log.Fatal("invalid webhook signature")
}
_ = payload
event, err := v.ConstructEvent(sigHeader, rawBody)
if err != nil {
log.Fatal(err)
}
fmt.Println(event.Event, event.ID)Authenticate and refresh user sessions using sealed cookies:
session := workos.NewSession(client, sealedCookie, cookiePassword)
result, err := session.Authenticate()
if err != nil {
log.Fatal(err)
}
if result.Authenticated {
fmt.Println("User:", result.User)
fmt.Println("Org:", result.OrganizationID)
}
refreshed, err := session.Refresh(ctx)
if err != nil {
log.Fatal(err)
}
if refreshed.Authenticated {
// Set refreshed.SealedSession as the new cookie value
}Store and retrieve encrypted key-value data with client-side encryption:
// KV operations
obj, _ := client.Vault().CreateObject(ctx, &workos.VaultCreateObjectParams{
Name: "api-token", Value: "secret-value",
})
read, _ := client.Vault().ReadObject(ctx, obj.ID)
// Client-side encryption (AES-256-GCM)
encrypted, _ := client.Vault().Encrypt(ctx, "sensitive data", keyContext, "")
decrypted, _ := client.Vault().Decrypt(ctx, encrypted.EncryptedData, "")Customize individual requests with functional options:
result, err := client.Organizations().Get(ctx, "org_123",
workos.WithTimeout(5 * time.Second),
workos.WithIdempotencyKey("unique-key"),
workos.WithExtraHeaders(http.Header{"X-Custom": {"value"}}),
)Build authorization URLs without making HTTP requests. For browser or other public PKCE flows, prefer workos.NewPublicClient(...):
// AuthKit with PKCE
publicClient := workos.NewPublicClient("<WORKOS_CLIENT_ID>")
result, err := publicClient.GetAuthorizationURL(workos.AuthKitAuthorizationURLParams{
RedirectURI: "https://example.com/callback",
})
fmt.Println(result.URL) // redirect the user here
fmt.Println(result.CodeVerifier) // store securely for token exchange
// SSO authorization
url, err := client.GetSSOAuthorizationURL(workos.SSOAuthorizationURLParams{
RedirectURI: "https://example.com/sso/callback",
ConnectionID: &connID,
})This SDK is a Go library that uses a flat package layout at the module root rather than an application-style project layout.
- The public API lives in the root
workospackage. - Tests are colocated in
*_test.gofiles, which is idiomatic for Go libraries. - Request and response fixtures live in
testdata/.
Import the root package:
import "github.com/workos/workos-go/v7"