Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Go SDK

go get -u github.com/scalekit-inc/scalekit-sdk-go
v2.2.0 Thread-safe Zero dependencies
Updated 5 days ago
View on GitHub
Initialize the client
package main


import (
    "os"
    "github.com/scalekit-inc/scalekit-sdk-go/scalekit"
)


func main() {
    scalekitClient := scalekit.NewScalekitClient(
        os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
        os.Getenv("SCALEKIT_CLIENT_ID"),
        os.Getenv("SCALEKIT_CLIENT_SECRET"),
    )
    // Use scalekitClient for authentication
}

Changelog

View all releases →

v2.2.0

Release Notes v2.2.0

Release date: 2026-03-06
Previous release: v2.1.0 (2026-02-24)

PRs included in this release

# Title
#45 API tokens
#50 chore: add CODEOWNERS
#58 Structured error handling, sentinel errors, and thread-safe client

New Features

API Token Management (token.go)

A new TokenClient is available on ScalekitClient for managing API tokens programmatically:

  • Create tokens - user-scoped or machine tokens with optional expiry
  • List tokens - filter by user ID or token type
  • Revoke/delete tokens - revoke individual tokens or all tokens for a user
  • Validate tokens - validate a raw token string; returns structured claims
// Example
token, err := client.Token().CreateToken(ctx, scalekit.CreateTokenOptions{...})

Structured Error Handling

Non-2xx HTTP responses are now surfaced as *scalekit.Error with an inspectable StatusCode field:

var e *scalekit.Error
if errors.As(err, &e) {
    fmt.Println(e.StatusCode) // e.g. 403
}

Sentinel Errors

Callers can now use errors.Is instead of string matching for common failure modes:

Sentinel Condition
ErrTokenRequired empty token passed to ValidateToken
ErrTokenValidationFailed token validation connect error
ErrMissingExpClaim token lacks exp claim
ErrCodeOrLinkTokenRequired missing code/link token
ErrOrganizationIdRequired missing org ID
ErrDirectoryNotFound directory lookup returned nothing

Improvements

Thread Safety

  • accessToken and jsonWebKeySet now use atomic.Pointer with singleflight groups — eliminates data races on concurrent requests.
  • JWKS read lock removed in favour of atomic load.

HTTP Client Hardening

  • A 10s default timeout is attached to every outbound request via withDefaultTimeout. Callers with their own context.Deadline are unaffected.
  • Auth retry is now scoped to genuine 401 / CodeUnauthenticated responses only; authenticateClient failures are propagated instead of silently ignored.

API Version Header

  • x-api-version header updated to 20260226.

Breaking Changes

None. A potentially breaking change (removal of external ID field) was reverted before this release. All existing method signatures remain compatible with v2.1.0.

Internal / Chore

  • Added .github/CODEOWNERS to enforce required reviews on all PRs (owners: @AkshayParihar33, @dhawani).
  • Proto stubs regenerated from source; ListTokensRequest.UserId changed to *string pointer.
  • go.mod updated.

Upgrade

go get github.com/scalekit-inc/scalekit-sdk-go/v2@v2.2.0

v2.1.0

v2.1.0

⚠️ Breaking Changes

All methods that make network calls now require a context.Context as the first argument to support cancellation or timeout propagation.

Method Old Signature New Signature
AuthenticateWithCode (code, redirectUri, options) (ctx, code, redirectUri, options)
ValidateAccessToken (accessToken) (ctx, accessToken)
GetAccessTokenClaims (accessToken) (ctx, accessToken)
GetIdpInitiatedLoginClaims (token) (ctx, token)
RefreshAccessToken (refreshToken) (ctx, refreshToken)
ValidateToken (token, jwksFn) (ctx, token, jwksFn)

Migration: Pass ctx as the first argument.

// Before
scalekitClient.AuthenticateWithCode(token)

// After
scalekitClient.AuthenticateWithCode(ctx, token)

✨ New Features

  • Connection.CreateConnection — programmatically create SSO connections for an organization
  • Connection.DeleteConnection — delete an existing SSO connection
  • Directory.CreateDirectory — programmatically create a directory for an organization
  • Directory.DeleteDirectory — delete an existing directory

v2.0.10

What's Changed

New Contributors

Full Changelog: v2.0.9...v2.0.10

Domain List API - Release Summary

Overview

Enhanced the ListDomains API with filtering and pagination capabilities to provide more flexible and efficient domain management operations.

Changes

New Features

1. Domain Type Filtering

The ListDomains API now supports filtering domains by type:

  • ALLOWED_EMAIL_DOMAIN: Filter for allowed email domains only
  • ORGANIZATION_DOMAIN: Filter for organization domains only
  • DOMAIN_TYPE_UNSPECIFIED: Unspecified domain type

Usage Example:

// List only organization domains
orgDomains, err := client.Domain().ListDomains(ctx, organizationId, &scalekit.ListDomainOptions{
    DomainType: scalekit.DomainTypeOrganization,
})

// List only allowed email domains
allowedEmailDomains, err := client.Domain().ListDomains(ctx, organizationId, &scalekit.ListDomainOptions{
    DomainType: scalekit.DomainTypeAllowedEmail,
})

2. Pagination Support

Added pagination controls to manage large result sets:

  • PageSize: Number of domains to return per page (default: 100)
  • PageNumber: Page number to retrieve (1-indexed)

Usage Example:

// List domains with custom pagination
domains, err := client.Domain().ListDomains(ctx, organizationId, &scalekit.ListDomainOptions{
    PageSize:   50,
    PageNumber: 1,
})

3. Combined Filtering and Pagination

Filter and paginate simultaneously for efficient domain queries:

Usage Example:

// List organization domains with pagination
orgDomains, err := client.Domain().ListDomains(ctx, organizationId, &scalekit.ListDomainOptions{
    DomainType: scalekit.DomainTypeOrganization,
    PageSize:   25,
    PageNumber: 1,
})

API Signature

Before:

ListDomains(ctx context.Context, organizationId string) (*ListDomainResponse, error)

After:

ListDomains(ctx context.Context, organizationId string, options ...*ListDomainOptions) (*ListDomainResponse, error)

Backward Compatibility

✅ Fully backward compatible - The API can still be called without options:

// Still works - returns all domains with default page size of 10
allDomains, err := client.Domain().ListDomains(ctx, organizationId)

New Types

ListDomainOptions

type ListDomainOptions struct {
    DomainType DomainType  // Optional: Filter by domain type
    PageSize   uint32      // Optional: Number of results per page (default: 10)
    PageNumber uint32      // Optional: Page number to retrieve
}

Implementation Details

Default Behavior

  • When no options are provided, the API returns all domains with a default page size of 10
  • Domain type filtering is optional and can be omitted
  • Pagination parameters are optional; if not specified, default page size applies

Type Conversion

The SDK automatically converts string domain type constants to the appropriate gRPC enum values:

  • scalekit.DomainTypeAllowedEmail → domains.DomainType_ALLOWED_EMAIL_DOMAIN
  • scalekit.DomainTypeOrganization → domains.DomainType_ORGANIZATION_DOMAIN
  • scalekit.DomainTypeUnspecified → domains.DomainType_DOMAIN_TYPE_UNSPECIFIED

Testing

Comprehensive test coverage has been added in test/domain_test.go:

  • ✅ Test listing all domains (no filter)
  • ✅ Test filtering by ORGANIZATION_DOMAIN type
  • ✅ Test filtering by ALLOWED_EMAIL_DOMAIN type
  • ✅ Test verification that filtered results only contain domains of the specified type
  • ✅ Test that created domains appear in the list

Migration Guide

No Changes Required

Existing code continues to work without modification:

// Existing code - no changes needed
domains, err := client.Domain().ListDomains(ctx, organizationId)

Optional: Add Filtering

To take advantage of new filtering capabilities:

// New: Filter by domain type
orgDomains, err := client.Domain().ListDomains(ctx, organizationId, &scalekit.ListDomainOptions{
    DomainType: scalekit.DomainTypeOrganization,
})

Benefits

  1. Performance: Filtering reduces unnecessary data transfer and processing
  2. Scalability: Pagination enables handling of large domain lists efficiently
  3. Flexibility: Combined filtering and pagination for precise queries
  4. Backward Compatibility: No breaking changes to existing implementations

Related Files

  • domain.go: Core implementation with ListDomainOptions and enhanced ListDomains method
  • test/domain_test.go: Comprehensive test suite including TestListDomains function
  • pkg/grpc/scalekit/v1/domains/: gRPC protocol buffer definitions

v2.0.9

What's Changed

  • Add WebAuthn sdk methods in #41

Full Changelog: v2.0.8...v2.0.9

v2.0.8

What's Changed

  • Added support for Bring your own Auth for MCP Servers in #39

Full Changelog: v2.0.7...v2.0.8

v2.0.7

What's Changed

New sdk methods

  • Add user management settings to organization API by @dhaneshbs in #38

Full Changelog: v2.0.6...v2.0.7

v2.0.6

What's Changed

Generate proto files to support given_name and family_name in user object in #37

Full Changelog: v2.0.5...v2.0.6

v2.0.5

What's Changed

  • Added Session management sdk methods & interceptorpayload verification method #34

Full Changelog: v2.0.4...v2.0.5