Skip to content
Scalekit Docs
Talk to an EngineerDashboard

Go SDK

Install

GitHub
go get -u github.com/scalekit-inc/scalekit-sdk-go
v2.8.0Thread-safeZero dependenciesUpdated 1 week ago

Initialize

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.8.0

What's Changed

  • [SK-1339] feat: typed UpdateLoginUserDetails response, issuer validation, listEventsPaginated by @AkshayParihar33 in #88

Full Changelog: v2.7.0...v2.8.0

v2.7.0

What's Changed

Full Changelog: v2.6.0...v2.7.0

v2.5.0

What's Changed

Full Changelog: v2.4.0...v2.5.0

v2.4.0

Added

  • Multi-app client management support with Client() APIs for client CRUD and client secret management.
  • PKCE helper support via GeneratePKCEConfiguration(...) for public client authorization flows.
  • WithSecret(...) to derive a secret-enabled client without mutating the original client.
  • ValidateTokenWithOptions(...) with audience and scope validation support.

Changed

  • NewScalekitClient(...) now supports initialization without a client secret for public clients while preserving backward compatibility.
  • GenerateClientToken(...) now accepts structured options and returns token metadata.
  • RefreshAccessToken(...) now includes id_token in the response.
  • SDK and API versions were updated, along with regenerated gRPC/Connect client code.

Fixed

  • AuthenticateWithCode(...) and RefreshAccessToken(...) now send client_secret only when configured.
  • Clear fail-fast errors are now returned when authenticated API calls require a client secret but none is configured.
v2.3.0
  • Document DeleteMembership cascade param
  • feat: add DeleteRoleBase for env-level role inheritance removal
  • feat: change ListPermissions signature to accept pageToken and pageSize
  • feat add global ListUsers to Go UserService interface
  • feat: add ValidateToken, GenerateClientToken, GetClientAccessToken to Scalekit interface
  • chore: bump version to 2.3.0, api-version to 20260310
  • fix: surface deleteEnvRole failures instead of swallowing them
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