WorkOS Go

https://github.com/workos/workos-go
Admin
WorkOS Go is a Go client library for the WorkOS API that provides access to authentication,...
Tokens:165,554
Snippets:943
Trust Score:9.9
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Create WorkOS client and get organization

Source: https://github.com/workos/workos-go/blob/main/README.md

Shows how to create a WorkOS client with an API key and client ID, then fetch an organization by ID. The example uses the Organizations service accessor and logs a fatal error if the request fails.

```go
package main

import (
	"context"
	"log"

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

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
}
```

--------------------------------

### Device authorization flow usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/auth_helpers.md

Example of starting a device authorization, polling for the result, and sealing the session from the authentication response. Handles cancellation and errors.

```go
device, err := client.AuthKitStartDeviceAuthorization(ctx)
if err != nil { log.Fatal(err) }
fmt.Println(device.VerificationURI, device.UserCode)

resp, err := client.AuthKitPollDeviceCode(ctx, device.DeviceCode, device.Interval != nil ? int(*device.Interval) : 5)
if err != nil {
	var cancelled = ctx.Err()
	if cancelled != nil { log.Printf("polling cancelled: %v", cancelled) }
	log.Fatal(err)
}
sealed, err := workos.SealSessionFromAuthResponse(resp.AccessToken, resp.RefreshToken, resp.User, resp.Impersonator, cookiePassword)
```

--------------------------------

### Get access token example for GitHub

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/pipes.md

Example call to GetAccessToken for the GitHub provider. Checks the Active flag to use the token or logs the reauthorization error.

```go
token, err := client.Pipes().GetAccessToken(ctx, "github", &workos.PipesGetAccessTokenParams{
	UserID: workos.String("user_123"),
})
if err != nil { log.Fatal(err) }
if token.Active == true {
	use(token.AccessToken.Value)
} else {
	log.Printf("reauthorization needed: %s", token.Error)
}
```

--------------------------------

### List users example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/directory_sync.md

Example of listing directory users with directory and group filters. Iterates over results and handles errors, including rate limit errors.

```go
iter := client.DirectorySync().ListUsers(ctx, &workos.DirectorySyncListUsersParams{
	Directory: workos.String("dir_123"),
	Group:     workos.String("group_456"),
})
for iter.Next() {
	user := iter.Current()
	fmt.Println(user.Email, user.State)
}
// Errors surface through iter.Err(); typed errors are inspectable via errors.As:
if err := iter.Err(); err != nil {
	var rate *workos.RateLimitExceededError
	if errors.As(err, &rate) { log.Printf("rate limited, retry after %ds", rate.RetryAfter) }
}
```

--------------------------------

### List directories example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/directory_sync.md

Example of listing directories with an organization filter. Iterates over results and handles errors, including rate limit errors.

```go
iter := client.DirectorySync().List(ctx, &workos.DirectorySyncListParams{
	OrganizationID: workos.String("org_123"),
})
for iter.Next() {
	dir := iter.Current()
	fmt.Println(dir.Name, dir.Type)
}
if err := iter.Err(); err != nil {
	var rate *workos.RateLimitExceededError
	if errors.As(err, &rate) { log.Printf("rate limited: %v", rate.Message) }
	log.Fatal(err)
}
```

--------------------------------

### Install WorkOS Go library with go get

Source: https://github.com/workos/workos-go/blob/main/README.md

Installs the WorkOS Go library. Requires Go 1.23+.

```bash
go get github.com/workos/workos-go/v10
```

--------------------------------

### CreateConnection usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/sso.md

Example of creating a SAML connection with IdP metadata. On error, it checks for an UnprocessableEntityError and logs the message.

```go
conn, err := client.SSO().CreateConnection(ctx, &workos.SSOCreateConnectionParams{
	OrganizationID: "org_123",
	Name:           workos.String("Acme IdP"),
	ProtocolOptions: &workos.SSOCreateProtocolOptionsSAML{
		SAMLOptions: workos.CreateConnectionSAMLOptions{
			IdpEntityId: "https://idp.example.com",
			IdpSsoUrl:   "https://idp.example.com/sso",
			IdpCert:     "-----BEGIN CERTIFICATE-----...",
		},
	},
})
if err != nil {
	var unprocessable *workos.UnprocessableEntityError
	if errors.As(err, &unprocessable) {
		log.Printf("invalid connection config: %s", unprocessable.Message)
	}
	return
}
```

--------------------------------

### Create organization usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/organizations.md

Example of creating an organization with name, domain data, metadata, and no explicit nulls. Error handling uses errors.As to check for workos.APIError and logs the code and message.

```go
org, err := client.Organizations().Create(ctx, &workos.OrganizationsCreateParams{
	Name:       "Acme Inc",
	DomainData: []*workos.OrganizationDomainData{
		&workos.OrganizationDomainData{Domain: "acme.com", State: workos.String("verified")},
	},
	Metadata:  map[string]string{"tier": "enterprise"},
	NullFields: []string{}, // no explicit nulls
})
if err != nil {
	var apiErr *workos.APIError
	if errors.As(err, &apiErr) { log.Printf("code=%s msg=%s", apiErr.code(), apiErr.Message) }
}
```

--------------------------------

### Directory groups list and get methods

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/directory_sync.md

Defines the parameters and methods for listing and getting directory groups.

```go
type DirectorySyncListGroupsParams struct {
	PaginationParams
	Directory *string `url:"directory,omitempty"`   // WorkOS directory ID
	User *string      `url:"user,omitempty"`        // WorkOS directory user ID
}
func (s *DirectorySyncService) ListGroups(ctx context.Context, params *DirectorySyncListGroupsParams, opts ...RequestOption) *Iterator[DirectoryGroup]
// GET /directory_groups

func (s *DirectorySyncService) GetGroup(ctx context.Context, id string, opts ...RequestOption) (*DirectoryGroup, error)
// GET /directory_groups/{id}
```

--------------------------------

### Create user with plaintext password example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/user_management.md

Example of creating a user with a plaintext password using the Create method. Includes email, first name, last name, metadata, and password. Handles validation errors by checking for UnprocessableEntityError and logging field errors.

```go
// create with a plaintext password
user, err := client.UserManagement().Create(ctx, &workos.UserManagementCreateParams{
	Email:    "ada@example.com",
	FirstName: workos.String("Ada"),
	LastName:  workos.String("Lovelace"),
	Metadata: map[string]string{"plan": "pro"},
	Password: &workos.UserManagementPasswordPlaintext{
		Password: workos.String("s3cure-pass"),
	},
	NullFields: []string{},
})
if err != nil {
	var unprocessable *workos.UnprocessableEntityError
	if errors.As(err, &unprocessable) {
		log.Printf("validation failed: %v", unprocessable.FieldErrors)
	}
	return
}
```

--------------------------------

### ConstructEvent usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/webhooks.md

Example of constructing an event from a verified webhook payload and handling the event type.

```go
event, err := verifier.ConstructEvent(sigHeader, rawBody)
if err != nil {
	log.Fatal("invalid webhook signature or body")
}
fmt.Println(event.Event, event.ID)

switch event.Event {
case workos.CreateWebhookEndpointEventsUserCreated:
	// event.Data carries the typed payload fields
}
```

--------------------------------

### Get and Delete directory methods

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/directory_sync.md

Defines the Get and Delete methods for directories. Delete is permanent.

```go
func (s *DirectorySyncService) Get(ctx context.Context, id string, opts ...RequestOption) (*Directory, error)
// GET /directories/{id}

func (s *DirectorySyncService) Delete(ctx context.Context, id string, opts ...RequestOption) error
// DELETE /directories/{id} — permanent
```

--------------------------------

### AuthenticateWithPassword usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/user_management.md

Example of calling AuthenticateWithPassword. On MFAChallengeError, list the authentication factors and then finish with AuthenticateWithTOTP. On success, seal the session using SealSessionFromAuthResponse.

```go
resp, err := client.UserManagement().AuthenticateWithPassword(ctx, &workos.UserManagementAuthenticateWithPasswordParams{
	Email:    "user@example.com",
	Password: "correct horse battery staple",
	IPAddress: workos.String("203.0.113.72"),
})
if err != nil {
	var mfaErr *workos.MFAChallengeError
	if errors.As(err, &mfaErr) {
		// list mfaErr.AuthenticationFactors, then finish with AuthenticateWithTOTP
	}
	return
}
sealed, err := workos.SealSessionFromAuthResponse(resp.AccessToken, resp.RefreshToken, resp.User, resp.Impersonator, cookiePassword)
```

--------------------------------

### GeneratePKCEPair function signature and usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/auth_helpers.md

Generates a PKCE pair. The example shows error handling and printing the CodeChallengeMethod, which is "S256".

```go
func GeneratePKCEPair() (*PKCEPair, error)
```

```go
pair, err := workos.GeneratePKCEPair()
if err != nil { log.Fatal(err) }
fmt.Println(pair.CodeChallengeMethod) // "S256"
```

--------------------------------

### VerifyPayload usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/webhooks.md

Example of verifying a webhook payload and handling sentinel errors like ErrWebhookOutsideTolerance and ErrWebhookNoValidSignature.

```go
secret := endpoint.Secret
verifier := workos.NewWebhookVerifier(secret)

// rawBody is the request body as a string, e.g. string(bodyBytes).
payload, err := verifier.VerifyPayload(sigHeader, rawBody)
if err != nil {
	if errors.Is(err, workos.ErrWebhookOutsideTolerance) {
		log.Printf("replay or stale webhook")
	}
	if errors.Is(err, workos.ErrWebhookNoValidSignature) {
		log.Printf("bad signature")
	}
	return 400
}
_ = payload
```

--------------------------------

### Directory users list and get methods

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/directory_sync.md

Defines the parameters and methods for listing and getting directory users. IdpID and Email filters require the Directory parameter.

```go
type DirectorySyncListUsersParams struct {
	PaginationParams
	Directory *string `url:"directory,omitempty"`
	Group *string     `url:"group,omitempty"`
	IdpID *string     `url:"idp_id,omitempty"`   // requires directory
	Email *string     `url:"email,omitempty"`   // requires directory
}
func (s *DirectorySyncService) ListUsers(ctx context.Context, params *DirectorySyncListUsersParams, opts ...RequestOption) *Iterator[DirectoryUserWithGroups]
// GET /directory_users

func (s *DirectorySyncService) GetUser(ctx context.Context, id string, opts ...RequestOption) (*DirectoryUserWithGroups, error)
// GET /directory_users/{id}
```

--------------------------------

### Create organization membership example with error handling

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/groups.md

Example of creating an organization membership with a single role. It handles the UnprocessableEntityError that occurs when the user is already a member, logging the error message.

```go
om, err := client.OrganizationMembership().Create(ctx, &workos.OrganizationMembershipCreateParams{
	UserID:         "user_123",
	OrganizationID: "org_456",
	Role:           &workos.OrganizationMembershipRoleSingle{RoleSlug: "member"},
})
if err != nil {
	var unprocessable *workos.UnprocessableEntityError
	if errors.As(err, &unprocessable) { log.Printf("already a member: %s", unprocessable.Message) }
	return
}
```

--------------------------------

### List organizations usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/organizations.md

Example of listing organizations with a limit and search filter, iterating over results and printing organization ID and name. Handles iteration errors with log.Fatal.

```go
iter := client.Organizations().List(ctx, &workos.OrganizationsListParams{
	Limit:  workos.Int(25),
	Search: workos.String("acme"),
})
for iter.Next() {
	org := iter.Current()
	fmt.Println(org.ID, org.Name)
}
if err := iter.Err(); err != nil { log.Fatal(err) }
```

--------------------------------

### Create M2M Connect application with ConnectCreateM2MApplicationParams and usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/connect.md

Defines the parameters and method for creating an M2M Connect application, then shows a usage example. The method requires Name and OrganizationID and maps to the POST /connect/applications endpoint with application_type="m2m". The example creates an application named "Pipeline Worker" with scopes and handles a potential UnprocessableEntityError.

```go
type ConnectCreateM2MApplicationParams struct {
	Name string
	OrganizationID string
	Description *string
	Scopes []string
}

func (s *ConnectService) CreateM2MApplication(ctx context.Context, params *ConnectCreateM2MApplicationParams, opts ...RequestOption) (*ConnectApplication, error)
// POST /connect/applications with application_type="m2m"
```

```go
app, err := client.Connect().CreateM2MApplication(ctx, &workos.ConnectCreateM2MApplicationParams{
	Name:           "Pipeline Worker",
	OrganizationID: "org_123",
	Scopes:         []string{"read:jobs", "write:jobs"},
})
if err != nil {
	var unprocessable *workos.UnprocessableEntityError
	if errors.As(err, &unprocessable) { log.Printf("create failed: %s", unprocessable.Message) }
	return
}
```

--------------------------------

### ListKvMetadata and ListKvVersions methods

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/vault.md

Defines methods to list metadata and versions of a key-value object. ListKvMetadata uses GET /vault/v1/kv/{id}/metadata without decryption, and ListKvVersions uses GET /vault/v1/kv/{id}/versions.

```go
func (s *VaultService) ListKvMetadata(ctx context.Context, id string, opts ...RequestOption) (*ObjectWithoutValue, error)
// GET /vault/v1/kv/{id}/metadata — no decryption

func (s *VaultService) ListKvVersions(ctx context.Context, id string, opts ...RequestOption) (*VersionListResponse, error)
// GET /vault/v1/kv/{id}/versions
```

--------------------------------

### UserManagementListParams, Create, Get, Update, Delete signatures

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/user_management.md

Type definitions and method signatures for listing, creating, retrieving, updating, and deleting users. List uses GET /user_management/users with optional filters. Create sends a POST to /user_management/users. GetByExternalID uses GET /user_management/users/external_id/{externalID}. Update uses PUT /user_management/users/{id}. Delete removes a user by ID.

```go
type UserManagementListParams struct {
	PaginationParams
	Organization *string // deprecated: use organization_id
	OrganizationID *string
	Email *string
}
func (s *UserManagementService) List(ctx context.Context, params *UserManagementListParams, opts ...RequestOption) *Iterator[User]
// GET /user_management/users

type UserManagementCreateParams struct {
	Email string                 // required
	FirstName, LastName, Name *string
	EmailVerified *bool
	Metadata map[string]string   // url:"-" — sent in body
	ExternalID *string
	IPAddress, UserAgent *string
	SignalsID *string
	Password UserManagementPassword            // interface: UserManagementPasswordPlaintext | UserManagementPasswordHashed
	NullFields []string
}
func (s *UserManagementService) Create(ctx context.Context, params *UserManagementCreateParams, opts ...RequestOption) (*UserCreateResponse, error)

func (s *UserManagementService) GetByExternalID(ctx context.Context, externalID string, opts ...RequestOption) (*User, error)
// GET /user_management/users/external_id/{externalID}
func (s *UserManagementService) Get(ctx context.Context, id string, opts ...RequestOption) (*User, error)

type UserManagementUpdateParams struct {
	Email, FirstName, LastName, Name, EmailVerified, Metadata, ExternalID, Locale — all * (pointer) except Metadata map[string]string
	Password UserManagementPassword
	NullFields []string
}
func (s *UserManagementService) Update(ctx context.Context, id string, params *UserManagementUpdateParams, opts ...RequestOption) (*User, error)
// PUT /user_management/users/{id}

func (s *UserManagementService) Delete(ctx context.Context, id string, opts ...RequestOption) error
```

--------------------------------

### Before: Old SDK imports and client initialization

Source: https://github.com/workos/workos-go/blob/main/docs/V7_MIGRATION_GUIDE.md

Shows the old SDK initialization with service-specific packages and package-level configuration helpers.

```go
import (
	"github.com/workos/workos-go/v6/pkg/directorysync"
	"github.com/workos/workos-go/v6/pkg/sso"
)

func main() {
	sso.Configure("<WORKOS_API_KEY>", "<CLIENT_ID>")
	directorysync.SetAPIKey("<WORKOS_API_KEY>")
}
```

--------------------------------

### After: New SDK imports and client initialization

Source: https://github.com/workos/workos-go/blob/main/docs/V7_MIGRATION_GUIDE.md

Shows the new SDK initialization with a single root package and a shared client, using workos.NewClient and workos.WithClientID.

```go
import "github.com/workos/workos-go/v6"

func main() {
	client := workos.NewClient(
		"<WORKOS_API_KEY>",
		workos.WithClientID("<CLIENT_ID>"),
	)
}
```

--------------------------------

### List events with iterator and error handling

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/events.md

Example of listing events with a limit, event type filter, and range start. It iterates over the results and handles potential rate limit errors.

```go
iter := client.Events().List(ctx, &workos.EventsListParams{
	Limit:     workos.Int(50),
	Events:    []string{"dsync.user.created"},
	RangeStart: workos.String("2024-01-01T00:00:00Z"),
})
for iter.Next() {
	event := iter.Current()
	fmt.Println(event.Event, event.ID, event.CreatedAt)
}
if err := iter.Err(); err != nil {
	var rate *workos.RateLimitExceededError
	if errors.As(err, &rate) { log.Printf("rate limited: retry after %d s", rate.RetryAfter) }
	log.Fatal(err)
}
```

--------------------------------

### Create and validate API key example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/api_keys.md

Shows how to create an organization API key, store it securely, and validate a presented key. Handles UnprocessableEntityError on creation and APIError with 404 on validation.

```go
key, err := client.APIKeys().CreateOrganizationAPIKey(ctx, "org_123", &workos.APIKeysCreateOrganizationAPIKeyParams{
	Name:        "deploy-key",
	Permissions: []string{"organizations:read"},
})
if err != nil {
	var unprocessable *workos.UnprocessableEntityError
	if errors.As(err, &unprocessable) { log.Printf("create failed: %s", unprocessable.Message) }
	return
}
storeSecurely(key.Value)

valid, err := client.APIKeys().CreateValidation(ctx, &workos.APIKeysCreateValidationParams{Value: presented})
if err != nil {
	var apiErr *workos.APIError
	if errors.As(err, &apiErr) && apiErr.StatusCode == 404 { log.Printf("invalid key") }
	return
}
_ = valid.APIKey
```

--------------------------------

### Get organization by external ID or ID

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/organizations.md

Retrieves an organization by external ID or internal ID. The external ID variant uses the GET /organizations/external_id/{externalID} endpoint, while the ID variant uses GET /organizations/{id}.

```go
func (s *OrganizationService) GetByExternalID(ctx context.Context, externalID string, opts ...RequestOption) (*Organization, error)
// GET /organizations/external_id/{externalID}

func (s *OrganizationService) Get(ctx context.Context, id string, opts ...RequestOption) (*Organization, error)
// GET /organizations/{id}
```

--------------------------------

### CreateToken usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/api_keys.md

Shows how to create a client API token for a specific organization and user, then use it with the Client GraphQL API.

```go
tok, err := client.ClientAPI().CreateToken(ctx, &workos.ClientAPICreateTokenParams{
	OrganizationID: "org_123",
	UserID:         "user_456",
})
if err != nil { log.Fatal(err) }
useWithClientGraphQLAPI(tok.Token)
```

--------------------------------

### List and enable feature flags example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/feature_flags.md

Shows how to iterate over all feature flags using the List method and how to enable a specific flag, handling a NotFoundError if the flag does not exist.

```go
iter := client.FeatureFlags().List(ctx, &workos.FeatureFlagsListParams{})
for iter.Next() {
	flag := iter.Current()
	fmt.Println(flag.Slug, flag.Enabled, flag.DefaultValue)
}
if err := iter.Err(); err != nil { log.Fatal(err) }

flag, err := client.FeatureFlags().Enable(ctx, "new-billing-ui")
if err != nil {
	var notFound *workos.NotFoundError
	if errors.As(err, &notFound) { log.Printf("unknown flag: %s", notFound.Message) }
	return
}
```

--------------------------------

### NewClient with full configuration

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/client.md

Full configuration of NewClient with all available options: client ID, base URL, max retries, timeout, logger, and app info. The logger must implement Logger{ Printf(format string, args ...any) }.

```go
client := workos.NewClient(
	"sk_...",
	workos.WithClientID("client_..."),
	workos.WithBaseURL("https://api.workos.com/"),
	workos.WithMaxRetries(5),
	workos.WithTimeout(30 * time.Second),
	workos.WithLogger(myLogger),   // Logger{ Printf(format string, args ...any) }
	workos.WithAppInfo("my-framework", "1.0.0", "https://example.com"),
)
```

--------------------------------

### GetAuthKitPKCEAuthorizationURL usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/auth_helpers.md

Example usage of GetAuthKitPKCEAuthorizationURL with a redirect URI. The result contains the URL, code verifier, and state.

```go
result, err := client.GetAuthKitPKCEAuthorizationURL(workos.AuthKitAuthorizationURLParams{
	RedirectURI: "https://example.com/callback",
})
if err != nil { log.Fatal(err) }
```

--------------------------------

### Get audit log configuration

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/organizations.md

Retrieves the audit log configuration for an organization. Uses the GET /organizations/{id}/audit_log_configuration endpoint.

```go
func (s *OrganizationService) GetAuditLogConfiguration(ctx context.Context, id string, opts ...RequestOption) (*AuditLogConfiguration, error)
// GET /organizations/{id}/audit_log_configuration
```

--------------------------------

### CreateAttempt usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/radar.md

Demonstrates how to initiate a risk assessment and handle the resulting verdict.

```go
verdict, err := client.Radar().CreateAttempt(ctx, &workos.RadarCreateAttemptParams{
	IPAddress:  "203.0.113.72",
	UserAgent:  userAgent,
	Email:      email,
	AuthMethod: workos.RadarStandaloneAssessRequestAuthMethodPassword,
	Action:     workos.RadarStandaloneAssessRequestActionSignIn,
})
if err != nil {
	var apiErr *workos.APIError
	if errors.As(err, &apiErr) { log.Printf("assessment failed: %s", apiErr.code()) }
	return
}
switch verdict.Verdict {
case workos.RadarStandaloneResponseVerdictChallenge:
	requireAdditionalVerification(verdict.AttemptID, verdict.Control)
case workos.RadarStandaloneResponseVerdictBlock:
	deny()
default:
	allow()
}
```

--------------------------------

### SealSessionFromAuthResponse usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/session.md

Example of using SealSessionFromAuthResponse after AuthenticateWithPassword to create a sealed session and set a cookie. It calls log.Fatal on errors.

```go
resp, err := client.UserManagement().AuthenticateWithPassword(ctx, &params)
if err != nil { log.Fatal(err) }
sealed, err := workos.SealSessionFromAuthResponse(resp.AccessToken, resp.RefreshToken, resp.User, resp.Impersonator, cookiePassword)
if err != nil { log.Fatal(err) }
setCookie(sealed)
```

--------------------------------

### Directory Sync: List after migration (v7)

Source: https://github.com/workos/workos-go/blob/main/docs/V7_MIGRATION_GUIDE.md

New SDK call to list directories, using the client and a params struct pointer. Returns an iterator.

```go
import "github.com/workos/workos-go/v6"

client := workos.NewClient("<WORKOS_API_KEY>")

iter := client.DirectorySync().List(ctx, &workos.DirectorySyncListParams{})
```

--------------------------------

### Environment Roles Methods (List, Create, Get, Update, Add/Set Permissions)

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/authorization.md

Methods for managing environment roles. ListEnvironmentRoles returns a RoleList, CreateEnvironmentRole creates a role, GetEnvironmentRole retrieves by slug, UpdateEnvironmentRole updates, AddEnvironmentRolePermission adds a permission, and SetEnvironmentRolePermissions sets permissions. These mirror organization roles but omit the organizationID path segment.

```go
func (s *AuthorizationService) ListEnvironmentRoles(ctx context.Context, opts ...RequestOption) (*RoleList, error)
func (s *AuthorizationService) CreateEnvironmentRole(ctx context.Context, params *AuthorizationCreateEnvironmentRoleParams, opts ...RequestOption) (*Role, error)
func (s *AuthorizationService) GetEnvironmentRole(ctx context.Context, slug string, opts ...RequestOption) (*Role, error)
func (s *AuthorizationService) UpdateEnvironmentRole(ctx context.Context, slug string, params *AuthorizationUpdateEnvironmentRoleParams, opts ...RequestOption) (*Role, error)
func (s *AuthorizationService) AddEnvironmentRolePermission(ctx context.Context, slug string, params *AuthorizationAddEnvironmentRolePermissionParams, opts ...RequestOption) (*Role, error)
func (s *AuthorizationService) SetEnvironmentRolePermissions(ctx context.Context, slug string, params *AuthorizationSetEnvironmentRolePermissionsParams, opts ...RequestOption) (*Role, error)
```

--------------------------------

### Authenticate a session and handle refresh

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/session.md

Shows how to create a session and call `Authenticate`. It checks `result.Authenticated` and `result.NeedsRefresh`; when a refresh is needed, it calls `session.Refresh(ctx)` and sets the new cookie value from `refreshed.SealedSession` if successful.

```go
session := workos.NewSession(client, sealedCookie, cookiePassword)

result, err := session.Authenticate()
if err != nil { log.Fatal(err) }
if !result.Authenticated {
	log.Printf("not authenticated: %s", result.Reason) // invalid_session_cookie, session_expired, ...
}
if result.NeedsRefresh {
	refreshed, err := session.Refresh(ctx)
	if err != nil { log.Fatal(err) }
	if refreshed.Authenticated {
		// set refreshed.SealedSession as the new cookie value
	}
	return
}
fmt.Println("User:", result.User)
```

--------------------------------

### Organizations: Create after migration (v7)

Source: https://github.com/workos/workos-go/blob/main/docs/V7_MIGRATION_GUIDE.md

New SDK call to create an organization, using the client and a params struct pointer.

```go
org, err := client.Organizations().Create(ctx, &workos.OrganizationsCreateParams{
	Name: "Acme",
})
```

--------------------------------

### Directory Sync: ListDirectories before migration (v6)

Source: https://github.com/workos/workos-go/blob/main/docs/V7_MIGRATION_GUIDE.md

Old SDK call to list directories, using an Opts struct. Requires setting the API key via directorysync.SetAPIKey.

```go
import "github.com/workos/workos-go/v6/pkg/directorysync"

directorysync.SetAPIKey("<WORKOS_API_KEY>")

resp, err := directorysync.ListDirectories(ctx, directorysync.ListDirectoriesOpts{})
```

--------------------------------

### Organizations: Get after migration (v7)

Source: https://github.com/workos/workos-go/blob/main/docs/V7_MIGRATION_GUIDE.md

New SDK call to get an organization, using the client and passing the organization ID directly. Requires creating a client with workos.NewClient.

```go
import "github.com/workos/workos-go/v6"

client := workos.NewClient("<WORKOS_API_KEY>")

org, err := client.Organizations().Get(ctx, "org_123")
```

--------------------------------

### GetName and GetKv methods

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/vault.md

Defines methods to retrieve a key-value object by name or by ID. GetName uses GET /vault/v1/kv/name/{name} and GetKv uses GET /vault/v1/kv/{id}.

```go
func (s *VaultService) GetName(ctx context.Context, name string, opts ...RequestOption) (*VaultObject, error)
// GET /vault/v1/kv/name/{name}

func (s *VaultService) GetKv(ctx context.Context, id string, opts ...RequestOption) (*VaultObject, error)
// GET /vault/v1/kv/{id}
```

--------------------------------

### NewClient

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/client.md

Documentation for the NewClient constructor function.

```APIDOC
## NewClient

### Description
Creates the WorkOS API client. The `apiKey` is required; `opts` configure the client. Every service field is instantiated in the constructor.

### Function Signature
`func NewClient(apiKey string, opts ...ClientOption) *Client`

### Parameters
- **apiKey** (string) - Required - The WorkOS API key.
- **opts** (ClientOption) - Optional - Configuration options for the client.

### Usage Example
```go
client := workos.NewClient(
	"<WORKOS_API_KEY>",
	workos.WithClientID("<WORKOS_CLIENT_ID>"),
)
```

### Full Configuration Example
```go
client := workos.NewClient(
	"sk_...",
	workos.WithClientID("client_..."),
	workos.WithBaseURL("https://api.workos.com/"),
	workos.WithMaxRetries(5),
	workos.WithTimeout(30 * time.Second),
	workos.WithLogger(myLogger),   // Logger{ Printf(format string, args ...any) }
	workos.WithAppInfo("my-framework", "1.0.0", "https://example.com"),
)
```

### Errors
`NewClient` itself does not perform I/O and returns no error.
```

--------------------------------

### Create a webhook endpoint with client.Webhooks().CreateEndpoint

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/webhooks.md

Shows how to create a webhook endpoint with the WorkOS Go SDK. The example subscribes to user.created and user.updated events, handles a potential UnprocessableEntityError, and stores the returned endpoint.Secret for later use with NewWebhookVerifier.

```go
endpoint, err := client.Webhooks().CreateEndpoint(ctx, &workos.WebhooksCreateEndpointParams{
	EndpointURL: "https://api.example.com/hooks",
	Events:      []workos.CreateWebhookEndpointEvents{
		workos.CreateWebhookEndpointEventsUserCreated,
		workos.CreateWebhookEndpointEventsUserUpdated,
	},
})
if err != nil {
	var unprocessable *workos.UnprocessableEntityError
	if errors.As(err, &unprocessable) { log.Printf("invalid endpoint: %s", unprocessable.Message) }
	return
}
webhookSecret := endpoint.Secret  // store; needed for NewWebhookVerifier
```

--------------------------------

### AddListEntry usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/radar.md

Demonstrates adding an IP address to a block list.

```go
added, err := client.Radar().AddListEntry(ctx,
	workos.RadarListTypeIPAddress,
	workos.RadarListActionBlock,
	&workos.RadarAddListEntryParams{Entry: "203.0.113.72"},
)
if err != nil {
	var unprocessable *workos.UnprocessableEntityError
	if errors.As(err, &unprocessable) { log.Printf("invalid entry: %s", unprocessable.Message) }
}
fmt.Println(added.Message) // e.g. entry already present
```

--------------------------------

### CompleteOAuth2 usage example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/connect.md

Example call to CompleteOAuth2 with an external auth ID and a user object. It handles a potential UnprocessableEntityError for email collisions and redirects using the returned RedirectURI.

```go
resp, err := client.Connect().CompleteOAuth2(ctx, &workos.ConnectCompleteOAuth2Params{
	ExternalAuthID: externalAuthID,
	User: &workos.UserObject{
		ID:    "user-ext-1",
		Email: "ada@example.com",
	},
})
if err != nil {
	var unprocessable *workos.UnprocessableEntityError
	if errors.As(err, &unprocessable) { log.Printf("email collision: %s", unprocessable.Message) }
	return
}
redirect(resp.RedirectURI)
```

--------------------------------

### Configure WorkOS client with options

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/options.md

Creates a WorkOS client with custom base URL, HTTP client, max retries, and client ID. Use to override defaults for all requests.

```go
client := workos.NewClient(
	"sk_...",
	workos.WithClientID("client_..."),
	workos.WithMaxRetries(5),
	workos.WithBaseURL("https://api.workos.com"),
	workos.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
)
```

--------------------------------

### AuthenticateWithRadarEmailChallenge - Go Example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/user_management.md

Example call to AuthenticateWithRadarEmailChallenge on the UserManagement client. Passes the code, radar challenge ID, and pending authentication token, and logs a fatal error if the call fails.

```go
resp, err := client.UserManagement().AuthenticateWithRadarEmailChallenge(ctx, &workos.UserManagementAuthenticateWithRadarEmailChallengeParams{
	Code:                      code,
	RadarChallengeID:          radarChallengeID,
	PendingAuthenticationToken: pendingToken,
})
if err != nil {
	log.Fatal(err)
}
```

--------------------------------

### Revoke a session with error handling (RevokeSession example)

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/agents.md

Example of revoking a session by ID. Handles a NotFoundError by logging the message. Prints the session status, which will be "revoked" on success.

```go
session, err := client.Agents().RevokeSession(ctx, "asi_123")
if err != nil {
	var notFound *workos.NotFoundError
	if errors.As(err, &notFound) { log.Printf("session not found: %s", notFound.Message) }
	return
}
fmt.Println(session.Status) // "revoked"
```

--------------------------------

### Evaluate user feature flags example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/feature_flags.md

Iterates over the feature flags for a specific user and shows how to conditionally show experimental UI based on the flag's default value and enabled state.

```go
iter := client.FeatureFlags().ListUserFeatureFlags(ctx, "user_123", &workos.FeatureFlagsListUserFeatureFlagsParams{})
for iter.Next() {
	flag := iter.Current()
	if flag.DefaultValue && flag.Enabled {
		showExperimentalUI()
	}
}
if err := iter.Err(); err != nil { log.Fatal(err) }
```

--------------------------------

### ListOrganizationDataIntegrationConfigurations method

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/radar.md

Lists every provider available to the organization with enabled state, custom scopes, and organization-managed credentials.

```go
func (s *PipesProviderService) ListOrganizationDataIntegrationConfigurations(ctx context.Context, organizationID string, opts ...RequestOption) (*DataIntegrationConfigurationListResponse, error)
// GET /organizations/{organizationID}/data_integration_configurations
```

--------------------------------

### Create audit log export example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/audit_logs.md

Shows how to create an audit log export using the WorkOS Go SDK. After creation, poll GetExport until the state is 'ready', then download the URL.

```go
exp, err := client.AuditLogs().CreateExport(ctx, &workos.AuditLogsCreateExportParams{
	OrganizationID: "org_123",
	RangeStart:     "2024-01-01T00:00:00Z",
	RangeEnd:       "2024-01-31T23:59:59Z",
	Actions:        []string{"user.login"},
})
if err != nil { log.Fatal(err) }
// poll GetExport until exp.State == "ready", then download exp.URL
```

--------------------------------

### Creating a Client and Using Pointer Helpers with OrganizationsCreateParams

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/options.md

First snippet creates a new WorkOS client with an API key and client ID via NewClient and WithClientID. Second snippet uses the pointer helper String to pass a pointer to a string literal for ExternalID in the OrganizationsCreateParams struct, demonstrating how to use pointer-helper functions for optional pointer fields.

```go
client := workos.NewClient(
	"sk_...",
	workos.WithClientID("client_..."),
)
```

```go
org, err := client.Organizations().Create(ctx, &workos.OrganizationsCreateParams{
	Name:      "Acme",
	ExternalID: workos.String("acme-ext-id"),
})
```

--------------------------------

### PKCE flow usage example: GetSSOPKCEAuthorizationURL and SSOPKCECodeExchange

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/sso.md

Shows how to generate an authorization URL and exchange the code for a token. Redirect the browser to authURL.URL, keep authURL.CodeVerifier and authURL.State secure, then call SSOPKCECodeExchange with the callback code. Handles the invalid_grant error when the code is already used or expired.

```go
authURL, err := client.GetSSOPKCEAuthorizationURL(workos.SSOAuthorizationURLParams{
	RedirectURI: "https://example.com/sso/callback",
})
if err != nil { log.Fatal(err) }
// redirect browser to authURL.URL; keep authURL.CodeVerifier and authURL.State secure
// ...callback...
token, err := client.SSOPKCECodeExchange(ctx, workos.SSOPKCECodeExchangeParams{
	Code:         callbackCode,
	CodeVerifier: codeVerifier,
})
if err != nil {
	var apiErr *workos.APIError
	if errors.As(err, &apiErr) && apiErr.ErrorCode == "invalid_grant" {
		log.Printf("code already used or expired")
	}
}
```

--------------------------------

### GET /user_management/jwt_template

Source: https://github.com/workos/workos-go/blob/main/_autodocs/endpoints.md

Retrieves the JWT template.

```APIDOC
## GET /user_management/jwt_template

### Description
Retrieves the JWT template.

### Method
GET

### Endpoint
/user_management/jwt_template

### Response
#### Success Response (200)
- **JWTTemplateResponse** - The JWT template response.

#### Response Example
```json
{
  "content": ""
}
```
```

--------------------------------

### Update audit log retention example

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/audit_logs.md

Example of updating audit log retention for an organization. It sets the retention period to 6 months and prints the resulting retention period in days. If the update fails with an UnprocessableEntityError, it logs the error message.

```go
retention, err := client.AuditLogs().UpdateOrganizationAuditLogsRetention(ctx, "org_123", &workos.AuditLogsUpdateOrganizationAuditLogsRetentionParams{
	Retention: &workos.AuditLogsRetentionGroupPeriod{Period: workos.UpdateAuditLogsRetentionRetentionPeriod6Months},
})
if err != nil {
	var unprocessable *workos.UnprocessableEntityError
	if errors.As(err, &unprocessable) { log.Printf("invalid retention: %s", unprocessable.Message) }
}
fmt.Println(retention.RetentionPeriodInDays)
```

--------------------------------

### Create and read a key-value object

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/vault.md

Example of creating a key-value object with a key context and then retrieving it by ID. Handles NotFoundError and prints the decrypted value.

```go
obj, err := client.Vault().CreateKv(ctx, &workos.VaultCreateKvParams{
	Name:      "api-token",
	Value:     "sk-secret-value",
	KeyContext: map[string]string{"organization_id": "org_123"},
})
if err != nil {
	var notFound *workos.NotFoundError
	if errors.As(err, &notFound) { log.Printf("org missing") }
	return
}
read, err := client.Vault().GetKv(ctx, obj.ID)
if err != nil { log.Fatal(err) }
fmt.Println(read.Value)
```

--------------------------------

### GET /authorization/roles/{slug}

Source: https://github.com/workos/workos-go/blob/main/_autodocs/endpoints.md

Retrieves a role by its slug.

```APIDOC
## GET /authorization/roles/{slug}

### Description
Retrieves a role by its slug.

### Method
GET

### Endpoint
/authorization/roles/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the role.

### Response
#### Success Response (200)
- **Role** (object) - The requested role.

```

--------------------------------

### GET /user_management/waitlists

Source: https://github.com/workos/workos-go/blob/main/_autodocs/endpoints.md

Lists waitlists (single page).

```APIDOC
## GET /user_management/waitlists

### Description
Lists waitlists (single page).

### Method
GET

### Endpoint
/user_management/waitlists

### Response
#### Success Response (200)
- **Iterator[Waitlist]** - A list of waitlists.

```

--------------------------------

### GetApplication / UpdateApplication / DeleteApplication

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/connect.md

Methods to get, update, and delete a Connect application. GetApplication accepts an ID or client ID and calls GET /connect/applications/{id}. UpdateApplication uses ConnectUpdateApplicationParams with nullable fields (description, scopes, redirect_uris) and calls PUT /connect/applications/{id}. DeleteApplication calls DELETE /connect/applications/{id}.

```go
func (s *ConnectService) GetApplication(ctx context.Context, id string, opts ...RequestOption) (*ConnectApplication, error)
// GET /connect/applications/{id} — ID or client ID
```

```go
type ConnectUpdateApplicationParams struct {
	Name *string
	Description *string
	Scopes []string
	RedirectURIs []*RedirectURIInput     // OAuth applications only
	NullFields []string                  // nullable: description, scopes, redirect_uris
}
func (s *ConnectService) UpdateApplication(ctx context.Context, id string, params *ConnectUpdateApplicationParams, opts ...RequestOption) (*ConnectApplication, error)
// PUT /connect/applications/{id}
```

```go
func (s *ConnectService) DeleteApplication(ctx context.Context, id string, opts ...RequestOption) error
```

--------------------------------

### Example: Check authorization for a permission

Source: https://github.com/workos/workos-go/blob/main/_autodocs/api-reference/authorization.md

Shows how to call the Check method with a permission slug and resource target by ID. Handles a NotFoundError if the membership or resource is missing, and checks the Authorized field to conditionally serve a document.

```go
check, err := client.Authorization().Check(ctx, "om_456", &workos.AuthorizationCheckParams{
	PermissionSlug: "doc:read",
	ResourceTarget: &workos.AuthorizationResourceTargetByID{ResourceID: "res_789"},
})
if err != nil {
	var notFound *workos.NotFoundError
	if errors.As(err, &notFound) { log.Printf("membership or resource missing: %s", notFound.Message) }
	return
}
if check.Authorized {
	serveDocument()
}
```

--------------------------------

### GET /user_management/redirect_uris

Source: https://github.com/workos/workos-go/blob/main/_autodocs/endpoints.md

Lists redirect URIs with pagination.

```APIDOC
## GET /user_management/redirect_uris

### Description
Lists redirect URIs with pagination.

### Method
GET

### Endpoint
/user_management/redirect_uris

### Parameters
#### Query Parameters
- **pagination** - Required - Pagination parameters.

### Response
#### Success Response (200)
- **Iterator[RedirectURI]** - An iterator of redirect URIs.
```

--------------------------------

### GET /user_management/invitations/{id}

Source: https://github.com/workos/workos-go/blob/main/_autodocs/endpoints.md

Retrieves an invitation by ID.

```APIDOC
## GET /user_management/invitations/{id}

### Description
Retrieves an invitation by ID.

### Method
GET

### Endpoint
/user_management/invitations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The invitation ID.

### Response
#### Success Response (200)
- **UserInvite** - The invitation object.

#### Response Example
```json
{
  "id": ""
}
```
```
Tokens:
Raw