Go SDK

go get -u github.com/workos/workos-go/...

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/v9

package main

import (
	"context"
	"log"

	"github.com/workos/workos-go/v9"
)

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, &notFound) {
		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 workos package.
• Tests are colocated in *_test.go files, which is idiomatic for Go libraries.
• Request and response fixtures live in testdata/.

Import the root package:

import "github.com/workos/workos-go/v9"