WorkOS Docs Homepage
SDKs
API referenceDashboardSign In
SDKs

Go SDK

github.com
workos/workos-go
67 Stars
22 Forks
53 Contributors
github.com
Official Go SDK for interacting with the WorkOS API.

Installation

Command Line
Go

Beta Versions

Certain WorkOS features may be available only in the beta version of the SDK. Beta versions have the -beta.* suffix, for example, 3.2.0-beta.1. For more information on how to use the beta versions, refer to the README in the GitHub repository.

Releases

September 5, 2025

v5.0.0

Latest
September 5, 2025

What's Changed

  • Re-introduce metadata removal support (breaking change) by @nicknisi in https://github.com/workos/workos-go/pull/457

Breaking Changes Summary

The v5 release includes the following breaking change:

  • UpdateUserOpts.Metadata field type changed from map[string]string to map[string]*string (introduced in PR #457)
  • This allows setting metadata values to nil to remove them server-side

Migration Guide for Users

// v4 (old)
import "github.com/workos/workos-go/v4/pkg/usermanagement"

opts := usermanagement.UpdateUserOpts{
    User: "user_123",
    Metadata: map[string]string{
        "department": "Engineering",
    },
}

// v5 (new)
import "github.com/workos/workos-go/v5/pkg/usermanagement"

dept := "Engineering"
opts := usermanagement.UpdateUserOpts{
    User: "user_123",
    Metadata: map[string]*string{
        "department": &dept,
        "old_field": nil,  // Removes this field
    },
}

Full Changelog: https://github.com/workos/workos-go/compare/v4.46.1...v5.0.0

September 5, 2025

v4.46.1

September 5, 2025

What's Changed

  • Fix: Revert breaking change in v4.46.0 to maintain backward compatibility by @nicknisi in https://github.com/workos/workos-go/pull/455

Full Changelog: https://github.com/workos/workos-go/compare/v4.46.0...v4.46.1

September 4, 2025

v4.46.0

September 4, 2025
  • Adds ability to pass in nil values to metadata keys when updating a user. This allows for clearing of existing metadata fields on a user.
August 20, 2025

v4.45.1

August 20, 2025
  • Correctly unmarshal list_metadata pagination cursors across User Management, Organizations, SSO, and Directory Sync
July 31, 2025

v4.45.0

July 31, 2025

  • Added structured authentication error handling for AuthKit User Management API

  • New error types for authentication scenarios:

    • EmailVerificationRequiredError
    • MFAEnrollmentError
    • MFAChallengeError
    • OrganizationSelectionRequiredError
    • SSORequiredError
    • OrganizationAuthenticationMethodsRequiredError

  • Enhanced error parsing with user data, pending tokens, and organization info

  • Backwards compatible - existing error handling unchanged

  • Type-safe using standard Go errors.As() pattern

July 28, 2025

v4.44.0

July 28, 2025

What's Changed

  • added StripeCustomerID to org struct by @rarevalo13 in https://github.com/workos/workos-go/pull/442

Full Changelog: https://github.com/workos/workos-go/compare/v4.43.0...v4.44.0

July 11, 2025

v4.43.0

July 11, 2025
  • Add metadata serialization for updating organizations
July 10, 2025

v4.42.0

July 10, 2025

What's Changed

  • add organization_domain created/updated/deleted events by @ajworkos in https://github.com/workos/workos-go/pull/435
  • fix: use standard 12-byte nonce for AES-GCM encryption in vault package by @hexedpackets in https://github.com/workos/workos-go/pull/438

Full Changelog: https://github.com/workos/workos-go/compare/v4.41.0...v4.42.0

June 25, 2025

v4.41.0

June 25, 2025

What's Changed

  • Added support for custom oauth scopes (https://github.com/workos/workos-go/pull/431)
  • Correctly deserialize ListIdentitiesResult as array (https://github.com/workos/workos-go/pull/433)

Full Changelog: https://github.com/workos/workos-go/compare/v4.40.0...v4.41.0

May 20, 2025

v4.40.0

May 20, 2025

What's Changed

  • Add Email to UpdateUserOpts by @cmatheson in https://github.com/workos/workos-go/pull/429
  • added omitempty to ExternalID field by @rarevalo13 in https://github.com/workos/workos-go/pull/428
  • Bump to v4.40.0 by @rarevalo13 in https://github.com/workos/workos-go/pull/430

Full Changelog: https://github.com/workos/workos-go/compare/v4.39.0...v4.40.0

May 19, 2025

v4.39.0

May 19, 2025

What's Changed

  • Add "warnings" field to FGA query and check response by @atainter in https://github.com/workos/workos-go/pull/426
  • Bump to v4.39.0 by @atainter in https://github.com/workos/workos-go/pull/427

Full Changelog: https://github.com/workos/workos-go/compare/v4.38.0...v4.39.0

May 6, 2025

v4.38.0

May 6, 2025

What's Changed

  • Support optional authenticated data in local encrypt/decrypt by @hexedpackets in https://github.com/workos/workos-go/pull/424

Full Changelog: https://github.com/workos/workos-go/compare/v4.37.0...v4.38.0

April 25, 2025

v4.37.0

April 25, 2025

What's Changed

  • Add CustomAttributes field to SSO Profile (#422)

Full Changelog: https://github.com/workos/workos-go/compare/v4.36.0...v4.37.0

April 22, 2025

v4.36.0

April 22, 2025

What's Changed

  • Added password_reset.succeeded event type (https://github.com/workos/workos-go/pull/419)

Full Changelog: https://github.com/workos/workos-go/compare/v4.35.0...v4.36.0

April 15, 2025

v4.35.0

April 15, 2025

What's Changed

  • Add OrganizationDomains package by @ajworkos in https://github.com/workos/workos-go/pull/412
  • Alias organization domain types by @ajworkos in https://github.com/workos/workos-go/pull/415
  • Add endpoints to interact with WorkOS Vault by @hexedpackets in https://github.com/workos/workos-go/pull/418

Full Changelog: https://github.com/workos/workos-go/compare/v4.33.0...v4.35.0

March 25, 2025

v4.33.0

March 25, 2025

What's Changed

  • Add 'policies' to FGA convert schema response by @atainter in https://github.com/workos/workos-go/pull/411

Full Changelog: https://github.com/workos/workos-go/compare/v4.32.0...v4.33.0

March 24, 2025

v4.32.0

March 24, 2025

What's Changed

  • ron: adding support for email verification by @rarevalo13 in https://github.com/workos/workos-go/pull/402
  • Add UpdateSchema and GetSchema to FGA package by @atainter in https://github.com/workos/workos-go/pull/409
  • Bump to version v4.32.0 by @atainter in https://github.com/workos/workos-go/pull/410

Full Changelog: https://github.com/workos/workos-go/compare/v4.31.0...v4.32.0

March 21, 2025

v4.31.0

March 21, 2025

What's Changed

  • Add email standard attribute to DirectoryUser and mark deprecated standard attributes (#401)
  • Mark emails, job_title, and username standard attributes as deprecated. Enable the equivalent auto-mapped custom attributes instead (#401)
  • Adds ExternalID and Metadata to users and organizations (#407)

Full Changelog: https://github.com/workos/workos-go/compare/v4.30.0...v4.31.0

February 21, 2025

v4.30.0

February 21, 2025

What's Changed

  • Added LastSignInAt to User (https://github.com/workos/workos-go/pull/398)

Full Changelog: https://github.com/workos/workos-go/compare/v4.29.0...v4.30.0

February 7, 2025

v4.29.0

February 7, 2025

What's Changed

  • Fix typo: deactived -> deactivated by @nicknisi in https://github.com/workos/workos-go/pull/394
  • Add domain_prefix to organization domains by @amygdalama in https://github.com/workos/workos-go/pull/395
  • ron: adding optional query params for PKCE flow by @rarevalo13 in https://github.com/workos/workos-go/pull/392
  • v4.29.0 by @nicknisi in https://github.com/workos/workos-go/pull/396

New Contributors

  • @nicknisi made their first contribution in https://github.com/workos/workos-go/pull/394

Full Changelog: https://github.com/workos/workos-go/compare/v4.28.0...v4.29.0

January 15, 2025

v4.28.0

January 15, 2025

Added

  • Added ReturnTo option to GetLogoutURLOpts (#390)

Full Changelog: https://github.com/workos/workos-go/compare/v4.27.0...v4.28.0

January 2, 2025

v4.27.0

January 2, 2025

Added

  • Add GET /organization/:orgId/roles API support (#388)

Full Changelog: https://github.com/workos/workos-go/compare/v4.26.0...v4.27.0

December 11, 2024

v4.26.0

December 11, 2024

What's Changed

  • fix: added organization events by @panbanda in https://github.com/workos/workos-go/pull/382
  • Add AuthenticationMethod to AuthenticateResponse. by @dezlitz in https://github.com/workos/workos-go/pull/366

New Contributors

  • @panbanda made their first contribution in https://github.com/workos/workos-go/pull/382
  • @dezlitz made their first contribution in https://github.com/workos/workos-go/pull/366

Full Changelog: https://github.com/workos/workos-go/compare/v4.25.0...v4.26.0

November 15, 2024

v4.25.0

November 15, 2024

Added

  • Add widgets get token API support (#378)

Full Changelog: https://github.com/workos/workos-go/compare/v4.24.0...v4.25.0

November 11, 2024

v4.24.0

November 11, 2024

Added

  • Added OrganizationID, State, VerificationToken, and VerificationStrategy fields to OrganizationDomain struct (https://github.com/workos/workos-go/pull/376)
November 6, 2024

v4.23.0

November 6, 2024

Added

  • Added organization domain events (https://github.com/workos/workos-go/pull/374)
October 21, 2024

v4.22.1

October 21, 2024

What's Changed

  • Add domain_verification intent by @PaulAsjes in https://github.com/workos/workos-go/pull/372

Full Changelog: https://github.com/workos/workos-go/compare/v4.22.0...v4.22.1

October 16, 2024

v4.22.0

October 16, 2024

What's Changed

  • Add "role" to profile in https://github.com/workos/workos-go/pull/367

Full Changelog: https://github.com/workos/workos-go/compare/v4.21.1...v4.22.0

October 16, 2024

v4.21.1

October 16, 2024

Added

  • Added additional event type to fix typo on the DirectoryGroupUserRemoved event
August 28, 2024

v4.21.0

August 28, 2024

Added

  • Added ConvertSchemaToResourceTypes and ConvertResourceTypesToSchema to FGA module (#364)