Go SDK Reference

ScalekitClient

client := scalekit.NewScalekitClient(envUrl, clientId, clientSecret) -> scalekit.Scalekit

📝 Description

Creates a new Scalekit Go SDK client.

The returned client provides high-level OAuth helpers (authorization URL, token exchange, token validation, webhook verification) and typed sub-clients for resource APIs (organizations, users, sessions, etc.).

🔌 Usage

import "github.com/scalekit-inc/scalekit-sdk-go/v2"

client := scalekit.NewScalekitClient(
  "<SCALEKIT_ENV_URL>",
  "<SCALEKIT_CLIENT_ID>",
  "<SCALEKIT_CLIENT_SECRET>",
)

⚙️ Parameters

envUrl: string - Your Scalekit environment URL (from the dashboard)

clientId: string - Scalekit client ID

clientSecret: string - Scalekit client secret

client.GetAuthorizationUrl(redirectUri, options) -> (*url.URL, error)

📝 Description

Utility method to generate the OAuth 2.0 authorization URL to initiate the SSO authentication flow.

This method doesn’t make any network calls. It returns a fully formed authorization URL that you can redirect users to.

🔌 Usage

authURL, err := client.GetAuthorizationUrl(
  "https://yourapp.com/auth/callback",
  scalekit.AuthorizationUrlOptions{
    State:          "random-state-value",
    OrganizationId: "org_123",
  },
)
if err != nil {
  // handle
}

// Redirect user to authURL.String()

⚙️ Parameters

redirectUri: string - The URL where users will be redirected after authentication (must match a configured redirect URI)

options: AuthorizationUrlOptions - Configuration for the authorization request

• Scopes []string - OAuth scopes to request (default: openid profile email)
• State string - Opaque value to maintain state between request and callback
• Nonce string - String value used to associate a client session with an ID Token
• LoginHint string - Hint about the login identifier the user might use
• DomainHint string - Domain hint to identify which organization’s IdP to use
• ConnectionId string - Specific SSO connection ID to use for authentication
• OrganizationId string - Organization ID to authenticate against
• Provider string - Social login provider (e.g., google, github, microsoft)
• CodeChallenge string - PKCE code challenge
• CodeChallengeMethod string - Method used to generate the code challenge (e.g., S256)
• Prompt string - Controls authentication behavior (e.g., login, consent)

client.AuthenticateWithCode(ctx, code, redirectUri, options) -> (*AuthenticationResponse, error)

📝 Description

Exchanges an authorization code for tokens and user information.

Call this in your redirect handler after receiving the code query parameter.

🔌 Usage

resp, err := client.AuthenticateWithCode(
  ctx,
  code,
  "https://yourapp.com/auth/callback",
  scalekit.AuthenticationOptions{},
)
if err != nil {
  // handle
}

accessToken := resp.AccessToken
user := resp.User
_ = accessToken
_ = user

⚙️ Parameters

ctx: context.Context - Request context for cancellation and timeout propagation

code: string - The authorization code received in the callback URL

redirectUri: string - The same redirect URI used in GetAuthorizationUrl (must match exactly)

options: AuthenticationOptions

• CodeVerifier string - PKCE code verifier (required if PKCE was used)

client.GetIdpInitiatedLoginClaims(ctx, idpInitiatedLoginToken) -> (*IdpInitiatedLoginClaims, error)

📝 Description

Extracts and validates claims from an IdP-initiated login token.

Use this method when handling IdP-initiated SSO flows, where authentication is initiated from the identity provider’s portal instead of your application.

🔌 Usage

claims, err := client.GetIdpInitiatedLoginClaims(ctx, idpInitiatedLoginToken)
if err != nil {
  // handle
}

// claims.ConnectionID, claims.OrganizationID, claims.LoginHint, claims.RelayState
_ = claims

⚙️ Parameters

ctx: context.Context - Request context for cancellation and timeout propagation

idpInitiatedLoginToken: string - The token received via IdP-initiated login

client.GetAccessTokenClaims(ctx, accessToken) -> (*AccessTokenClaims, error)

📝 Description

Parses and validates an access token and returns its claims.

🔌 Usage

claims, err := client.GetAccessTokenClaims(ctx, accessToken)
if err != nil {
  // handle
}
_ = claims

⚙️ Parameters

ctx: context.Context - Request context for cancellation and timeout propagation

accessToken: string - The JWT access token

client.ValidateAccessToken(ctx, accessToken) -> (bool, error)

📝 Description

Validates an access token (including expiration checks) and returns whether it is valid.

🔌 Usage

ok, err := client.ValidateAccessToken(ctx, accessToken)
if err != nil {
  // invalid
}
_ = ok

⚙️ Parameters

ctx: context.Context - Request context for cancellation and timeout propagation

accessToken: string - The JWT access token

client.RefreshAccessToken(ctx, refreshToken) -> (*TokenResponse, error)

📝 Description

Exchanges a refresh token for a new access token (and optionally a new refresh token).

🔌 Usage

tokens, err := client.RefreshAccessToken(ctx, refreshToken)
if err != nil {
  // handle
}
_ = tokens.AccessToken

⚙️ Parameters

ctx: context.Context - Request context for cancellation and timeout propagation

refreshToken: string - The refresh token

client.GetLogoutUrl(options) -> (*url.URL, error)

📝 Description

Generates a logout URL for OIDC logout flows.

🔌 Usage

logoutURL, err := client.GetLogoutUrl(scalekit.LogoutUrlOptions{
  IdTokenHint:           idToken,
  PostLogoutRedirectUri: "https://yourapp.com/",
  State:                "state",
})
if err != nil {
  // handle
}
_ = logoutURL

⚙️ Parameters

options: LogoutUrlOptions

• IdTokenHint string
• PostLogoutRedirectUri string
• State string

client.VerifyWebhookPayload(secret, headers, payload) -> (bool, error)

📝 Description

Verifies a Scalekit webhook payload signature using webhook-id, webhook-timestamp, and webhook-signature headers.

🔌 Usage

valid, err := client.VerifyWebhookPayload(
  "whsec_...",
  map[string]string{
    "webhook-id":        "webhook_123",
    "webhook-timestamp": "1730000000",
    "webhook-signature": "v1,base64sig",
  },
  []byte(`{"event":"user.created","data":{"id":"123"}}`),
)
if err != nil {
  // handle
}
_ = valid

⚙️ Parameters

secret: string - Your webhook signing secret (e.g. whsec_...)

headers: map[string]string - Request headers containing webhook signature fields

payload: []byte - Raw request body

client.VerifyInterceptorPayload(secret, headers, payload) -> (bool, error)

📝 Description

Verifies an interceptor payload signature. Uses the same signature format as webhooks.

🔌 Usage

valid, err := client.VerifyInterceptorPayload(secret, headers, payload)
if err != nil {
  // handle
}
_ = valid

⚙️ Parameters

secret: string

headers: map[string]string

payload: []byte

client.Connection() -> scalekit.Connection

📝 Description

Returns the Connections client (client.Connection()), used to manage and query SSO connections.

client.Organization() -> scalekit.Organization

📝 Description

Returns the Organizations client (client.Organization()), used to manage organizations (tenants).

client.User() -> scalekit.UserService

📝 Description

Returns the Users client (client.User()), used to manage users and memberships.

client.Domain() -> scalekit.Domain

📝 Description

Returns the Domains client (client.Domain()), used to manage and query domains for organizations.

client.Directory() -> scalekit.Directory

📝 Description

Returns the Directories client (client.Directory()), used to list directories and directory users/groups (SCIM/Directory Sync).

client.Session() -> scalekit.SessionService

📝 Description

Returns the Sessions client (client.Session()), used to list and revoke sessions.

client.Role() -> scalekit.RoleService

📝 Description

Returns the Roles client (client.Role()), used to manage roles and organization roles.

client.Permission() -> scalekit.PermissionService

📝 Description

Returns the Permissions client (client.Permission()), used to manage permissions and role-permission relationships.

client.Passwordless() -> scalekit.PasswordlessService

📝 Description

Returns the Passwordless client (client.Passwordless()), used for passwordless email flows (OTP / magic link).

client.WebAuthn() -> scalekit.WebAuthnService

📝 Description

Returns the WebAuthn client (client.WebAuthn()), used to manage passkey credentials.

client.Auth() -> scalekit.AuthService

📝 Description

Returns the Auth client (client.Auth()), used for Auth gRPC helper methods (e.g. update login user details).

client.Client() -> scalekit.ClientService

📝 Description

Returns the Client service (client.Client()), used to manage OIDC application clients and client secrets in the environment.

client.Token() -> scalekit.TokenService

📝 Description

Returns the API token service (client.Token()), used to create, validate, list, and revoke organization API tokens.

client.ValidateTokenWithOptions(ctx, token, options) -> (bool, error)

📝 Description

Validates a signed JWT (access token or ID token) and enforces optional checks such as audience and scope validation.

🔌 Usage

valid, err := client.ValidateTokenWithOptions(ctx, accessToken, &scalekit.ValidateTokenOptions{
  Audience: []string{"my-api"},
  Scopes:   []string{"read", "write"},
})
if err != nil {
  // handle
}
_ = valid

⚙️ Parameters

ctx: context.Context - Request context for cancellation and timeout propagation

token: string - The JWT token to validate

options: *ValidateTokenOptions

• Audience []string - Optional set of accepted aud claim values
• Scopes []string - Optional set of scopes that must be present in the token

client.ValidateToken(ctx, token) -> (Claims, error)

📝 Description

Validates the token signature and expiry, then returns all claims as a Claims map. For strongly-typed claim structs use the package-level generic ValidateToken[T] function directly.

🔌 Usage

claims, err := client.ValidateToken(ctx, idToken)
if err != nil {
  // handle
}
_ = claims

⚙️ Parameters

ctx: context.Context - Request context for cancellation and timeout propagation

token: string - The JWT token to validate

client.GeneratePKCEConfiguration(options) -> (*PKCEConfiguration, error)

📝 Description

Generates PKCE code verifier and challenge for OAuth authorization code flow.

🔌 Usage

pkce, err := client.GeneratePKCEConfiguration(scalekit.PKCEOptions{
  VerifierLength: 64,
})
if err != nil {
  // handle
}

// Use pkce.CodeVerifier in token exchange
// Use pkce.CodeChallenge and pkce.CodeChallengeMethod in authorization URL

⚙️ Parameters

options: PKCEOptions

• CodeChallengeMethod string - Optional: defaults to “S256”
• VerifierLength int - Optional: generated code verifier length (43-128, defaults to 64)
• CodeVerifier string - Optional: precomputed code verifier

client.WithSecret(clientSecret) -> scalekit.Scalekit

📝 Description

Returns a new Scalekit client instance with a different client secret. Useful when you need to make calls with different credentials in the same application.

🔌 Usage

clientWithNewSecret := client.WithSecret("new_client_secret")

⚙️ Parameters

clientSecret: string - New client secret to use

client.GenerateClientToken(ctx, options) -> (*ClientTokenResponse, error)

📝 Description

Creates a client-credentials access token using the OAuth client credentials grant type. Use this for service-to-service authentication without user context.

🔌 Usage

resp, err := client.GenerateClientToken(ctx, scalekit.GenerateClientTokenOptions{
  ClientID:     "service_client_id",
  ClientSecret: "service_client_secret",
  Scopes:       []string{"read", "write"},
})
if err != nil {
  // handle
}
_ = resp.AccessToken

⚙️ Parameters

ctx: context.Context - Request context for cancellation and timeout propagation

options: GenerateClientTokenOptions

• ClientID string - Required: OAuth client identifier
• ClientSecret string - Required: OAuth client secret
• Scopes []string - Optional: scopes to request

client.GetClientAccessToken(ctx) -> (string, error)

📝 Description

Generates an access token using the client credentials of the current client. Convenience method that calls GenerateClientToken with the client’s configured credentials.

🔌 Usage

accessToken, err := client.GetClientAccessToken(ctx)
if err != nil {
  // handle
}
_ = accessToken

⚙️ Parameters

ctx: context.Context - Request context for cancellation and timeout propagation

Clients

client.Client().CreateClient(ctx, client) -> (*CreateClientResponse, error)

📝 Description

Creates a new OIDC client in the environment.

🔌 Usage

import (
  clients "github.com/scalekit-inc/scalekit-sdk-go/v2/pkg/grpc/scalekit/v1/clients"
)

created, err := client.Client().CreateClient(ctx, &clients.CreateClient{
  Name:                   "My Application",
  ClientType:             "WEB_APP",
  PostLoginUris:          []string{"https://myapp.com/callback"},
  PostLogoutRedirectUris: []string{"https://myapp.com/logout"},
})
if err != nil {
  // handle
}
_ = created.Client

⚙️ Parameters

ctx: context.Context

client: *clients.CreateClient (package pkg/grpc/scalekit/v1/clients)

client.Client().GetClient(ctx, clientId) -> (*GetClientResponse, error)

📝 Description

Fetches an OIDC client by client ID.

🔌 Usage

got, err := client.Client().GetClient(ctx, "client_123")
if err != nil {
  // handle
}
_ = got.Client

⚙️ Parameters

ctx: context.Context

clientId: string

client.Client().ListClients(ctx, options) -> (*ListClientsResponse, error)

📝 Description

Lists OIDC clients in the environment with optional pagination.

🔌 Usage

clients, err := client.Client().ListClients(ctx, &scalekit.ListClientsOptions{
  PageSize:  10,
  PageToken: "",
})
if err != nil {
  // handle
}
for _, c := range clients.Clients {
  _ = c
}

⚙️ Parameters

ctx: context.Context

options: *ListClientsOptions - Pass nil to use server defaults

• PageSize uint32
• PageToken string

client.Client().UpdateClient(ctx, clientId, client, mask) -> (*UpdateClientResponse, error)

📝 Description

Updates an OIDC client by client ID with field mask for partial updates.

🔌 Usage

import (
  clients "github.com/scalekit-inc/scalekit-sdk-go/v2/pkg/grpc/scalekit/v1/clients"
  "google.golang.org/protobuf/types/known/fieldmaskpb"
)

updated, err := client.Client().UpdateClient(ctx, "client_123", &clients.UpdateClient{
  Name: "Updated Name",
}, &fieldmaskpb.FieldMask{
  Paths: []string{"name"},
})
if err != nil {
  // handle
}
_ = updated.Client

⚙️ Parameters

ctx: context.Context

clientId: string

client: *clients.UpdateClient

mask: *fieldmaskpb.FieldMask - Field mask specifying which fields to update

client.Client().DeleteClient(ctx, clientId) -> error

📝 Description

Deletes an OIDC client by client ID.

🔌 Usage

if err := client.Client().DeleteClient(ctx, "client_123"); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

clientId: string

client.Client().CreateClientSecret(ctx, clientId) -> (*CreateClientSecretResponse, error)

📝 Description

Creates a new client secret for an OIDC client.

🔌 Usage

secret, err := client.Client().CreateClientSecret(ctx, "client_123")
if err != nil {
  // handle
}
// Save the returned secret immediately; it may not be shown again.
_ = secret.Secret

⚙️ Parameters

ctx: context.Context

clientId: string

client.Client().DeleteClientSecret(ctx, clientId, secretId) -> error

📝 Description

Deletes a specific client secret from an OIDC client.

🔌 Usage

if err := client.Client().DeleteClientSecret(ctx, "client_123", "secret_456"); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

clientId: string

secretId: string

Organizations

client.Organization().CreateOrganization(ctx, name, options) -> (*CreateOrganizationResponse, error)

📝 Description

Creates a new organization (tenant).

Organizations represent your B2B customers. Use ExternalId to map Scalekit organizations to your internal identifiers.

🔌 Usage

import (
  "context"
  "fmt"

  "github.com/scalekit-inc/scalekit-sdk-go/v2"
)

ctx := context.Background()
org, err := client.Organization().CreateOrganization(ctx, "Acme Corporation", scalekit.CreateOrganizationOptions{
  ExternalId: "customer_12345",
  Metadata: map[string]string{
    "source": "signup",
  },
})
if err != nil {
  // handle
}

fmt.Println("Organization ID:", org.Organization.Id)

⚙️ Parameters

ctx: context.Context - Request context

name: string - Display name for the organization

options: CreateOrganizationOptions

• ExternalId string
• Metadata map[string]string

client.Organization().ListOrganization(ctx, options) -> (*ListOrganizationsResponse, error)

📝 Description

Retrieves a paginated list of organizations in your environment.

🔌 Usage

// Paginate through all organizations
orgs, err := client.Organization().ListOrganization(ctx, &scalekit.ListOrganizationOptions{
  PageSize:  10,
  PageToken: "",
})
if err != nil {
  // handle
}
for _, org := range orgs.Organizations {
  _ = org.Id
}

// Use server defaults
orgs, err = client.Organization().ListOrganization(ctx, nil)

⚙️ Parameters

ctx: context.Context

options: *ListOrganizationOptions — all fields optional; pass nil to use server defaults.

• PageSize uint32 — number of results per page (0 = server default)
• PageToken string — cursor from a previous response’s NextPageToken

client.Organization().GetOrganization(ctx, id) -> (*GetOrganizationResponse, error)

📝 Description

Fetches an organization by Scalekit organization ID.

🔌 Usage

org, err := client.Organization().GetOrganization(ctx, "org_123")
if err != nil {
  // handle
}
_ = org.Organization

⚙️ Parameters

ctx: context.Context

id: string - Scalekit organization ID

client.Organization().GetOrganizationByExternalId(ctx, externalId) -> (*GetOrganizationResponse, error)

📝 Description

Fetches an organization by your external ID (if set).

🔌 Usage

org, err := client.Organization().GetOrganizationByExternalId(ctx, "customer_12345")
if err != nil {
  // handle
}
_ = org.Organization

⚙️ Parameters

ctx: context.Context

externalId: string - Your system’s organization identifier

client.Organization().UpdateOrganization(ctx, id, organization) -> (*UpdateOrganizationResponse, error)

📝 Description

Updates an organization by Scalekit organization ID.

🔌 Usage

updated, err := client.Organization().UpdateOrganization(
  ctx,
  "org_123",
  &organizations.UpdateOrganization{
    DisplayName: func() *string { s := "Updated name"; return &s }(),
  },
)
if err != nil {
  // handle
}
_ = updated.Organization

⚙️ Parameters

ctx: context.Context

id: string - Scalekit organization ID

organization: *organizationsv1.UpdateOrganization - Fields to update

client.Organization().UpdateOrganizationByExternalId(ctx, externalId, organization) -> (*UpdateOrganizationResponse, error)

📝 Description

Updates an organization by your external ID.

🔌 Usage

updated, err := client.Organization().UpdateOrganizationByExternalId(
  ctx,
  "customer_12345",
  &organizations.UpdateOrganization{
    DisplayName: func() *string { s := "Updated name"; return &s }(),
  },
)
if err != nil {
  // handle
}
_ = updated.Organization

⚙️ Parameters

ctx: context.Context

externalId: string

organization: *organizationsv1.UpdateOrganization

client.Organization().DeleteOrganization(ctx, id) -> error

📝 Description

Deletes an organization by Scalekit organization ID.

🔌 Usage

if err := client.Organization().DeleteOrganization(ctx, "org_123"); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

id: string

client.Organization().GeneratePortalLink(ctx, organizationId) -> (*organizationsv1.Link, error)

📝 Description

Generates an admin portal link for an organization.

🔌 Usage

link, err := client.Organization().GeneratePortalLink(ctx, "org_123")
if err != nil {
  // handle
}
_ = link.Url

⚙️ Parameters

ctx: context.Context

organizationId: string

client.Organization().UpdateOrganizationSettings(ctx, id, settings) -> (*GetOrganizationResponse, error)

📝 Description

Updates organization settings (feature toggles).

🔌 Usage

resp, err := client.Organization().UpdateOrganizationSettings(ctx, "org_123", scalekit.OrganizationSettings{
  Features: []scalekit.Feature{
    {Name: "sso", Enabled: true},
    {Name: "dir_sync", Enabled: true},
  },
})
if err != nil {
  // handle
}
_ = resp.Organization.Settings

⚙️ Parameters

ctx: context.Context

id: string - Scalekit organization ID

settings: OrganizationSettings

• Features []Feature where Feature is { Name string; Enabled bool }

client.Organization().UpsertUserManagementSettings(ctx, organizationId, settings) -> (*organizationsv1.OrganizationUserManagementSettings, error)

📝 Description

Creates or updates user management settings for an organization.

🔌 Usage

maxUsers := int32(150)
settings, err := client.Organization().UpsertUserManagementSettings(
  ctx,
  "org_123",
  scalekit.OrganizationUserManagementSettings{
    MaxAllowedUsers: &maxUsers,
  },
)
if err != nil {
  // handle
}
_ = settings.MaxAllowedUsers

⚙️ Parameters

ctx: context.Context

organizationId: string

settings: OrganizationUserManagementSettings

• MaxAllowedUsers *int32

Connections

client.Connection().CreateConnection(ctx, organizationId, connection) -> (*CreateConnectionResponse, error)

📝 Description

Creates a new SSO connection for an organization.

🔌 Usage

import (
  connectionsv1 "github.com/scalekit-inc/scalekit-sdk-go/v2/pkg/grpc/scalekit/v1/connections"
)

created, err := client.Connection().CreateConnection(ctx, "org_123", &connectionsv1.CreateConnection{
  Provider:    connectionsv1.ConnectionProvider_OKTA,
  Type:        connectionsv1.ConnectionType_SAML,
  ProviderKey: "my-okta-connection",
})
if err != nil {
  // handle
}
_ = created.Connection

⚙️ Parameters

ctx: context.Context

organizationId: string - Organization ID

connection: *connectionsv1.CreateConnection

client.Connection().DeleteConnection(ctx, organizationId, id) -> error

📝 Description

Deletes a connection by ID within an organization.

🔌 Usage

if err := client.Connection().DeleteConnection(ctx, "org_123", "conn_456"); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

organizationId: string - Organization ID

id: string - Connection ID

client.Connection().GetConnection(ctx, organizationId, id) -> (*GetConnectionResponse, error)

📝 Description

Fetches a connection by ID within an organization.

🔌 Usage

conn, err := client.Connection().GetConnection(ctx, "org_123", "conn_123")
if err != nil {
  // handle
}
_ = conn.Connection

⚙️ Parameters

ctx: context.Context

organizationId: string

id: string - Connection ID

client.Connection().ListConnectionsByDomain(ctx, domain) -> (*ListConnectionsResponse, error)

📝 Description

Lists connections that match a given domain (e.g. to support domain discovery for SSO).

🔌 Usage

conns, err := client.Connection().ListConnectionsByDomain(ctx, "acme.com")
if err != nil {
  // handle
}
_ = conns.Connections

⚙️ Parameters

ctx: context.Context

domain: string

client.Connection().ListConnections(ctx, organizationId) -> (*ListConnectionsResponse, error)

📝 Description

Lists all connections for an organization.

🔌 Usage

conns, err := client.Connection().ListConnections(ctx, "org_123")
if err != nil {
  // handle
}
_ = conns.Connections

⚙️ Parameters

ctx: context.Context

organizationId: string

client.Connection().EnableConnection(ctx, organizationId, id) -> (*ToggleConnectionResponse, error)

📝 Description

Enables a connection for an organization.

🔌 Usage

resp, err := client.Connection().EnableConnection(ctx, "org_123", "conn_123")
if err != nil {
  // handle
}
_ = resp.Enabled

⚙️ Parameters

ctx: context.Context

organizationId: string

id: string

client.Connection().DisableConnection(ctx, organizationId, id) -> (*ToggleConnectionResponse, error)

📝 Description

Disables a connection for an organization.

🔌 Usage

resp, err := client.Connection().DisableConnection(ctx, "org_123", "conn_123")
if err != nil {
  // handle
}
_ = resp.Enabled

⚙️ Parameters

ctx: context.Context

organizationId: string

id: string

Users

client.User().ListUsers(ctx, options) -> (*ListUsersResponse, error)

📝 Description

Lists users across the environment with optional pagination. Pass nil options to use server defaults.

🔌 Usage

users, err := client.User().ListUsers(ctx, &scalekit.ListUsersOptions{
  PageSize:  50,
  PageToken: "",
})
if err != nil {
  // handle
}
for _, u := range users.Users {
  _ = u
}

⚙️ Parameters

ctx: context.Context

options: *ListUsersOptions - Pass nil to use server defaults

• PageSize uint32
• PageToken string

client.User().ListOrganizationUsers(ctx, organizationId, options) -> (*ListOrganizationUsersResponse, error)

📝 Description

Lists users in an organization (paginated).

🔌 Usage

users, err := client.User().ListOrganizationUsers(ctx, "org_123", &scalekit.ListUsersOptions{
  PageSize:  10,
  PageToken: "",
})
if err != nil {
  // handle
}
_ = users.Users

⚙️ Parameters

ctx: context.Context

organizationId: string

options: *ListUsersOptions

• PageSize uint32
• PageToken string

client.User().GetUser(ctx, userId) -> (*GetUserResponse, error)

📝 Description

Fetches a user by user ID.

🔌 Usage

user, err := client.User().GetUser(ctx, "usr_123")
if err != nil {
  // handle
}
_ = user.User

⚙️ Parameters

ctx: context.Context

userId: string

client.User().UpdateUser(ctx, userId, updateUser) -> (*UpdateUserResponse, error)

📝 Description

Updates a user by user ID.

🔌 Usage

firstName := "Test"
lastName := "User"
name := "Test User"
locale := "en-US"

updated, err := client.User().UpdateUser(ctx, "usr_123", &users.UpdateUser{
  UserProfile: &users.UpdateUserProfile{
    FirstName: &firstName,
    LastName:  &lastName,
    Name:      &name,
    Locale:    &locale,
  },
})
if err != nil {
  // handle
}
_ = updated.User

⚙️ Parameters

ctx: context.Context

userId: string

updateUser: *usersv1.UpdateUser

client.User().CreateUserAndMembership(ctx, organizationId, user, sendInvitationEmail) -> (*CreateUserAndMembershipResponse, error)

📝 Description

Creates a user and adds them to an organization with a membership.

🔌 Usage

created, err := client.User().CreateUserAndMembership(ctx, "org_123", &users.CreateUser{
  Email: "test.user@example.com",
  Metadata: map[string]string{
    "source": "test",
  },
}, true)
if err != nil {
  // handle
}
_ = created.User.Id

⚙️ Parameters

ctx: context.Context

organizationId: string

user: *usersv1.CreateUser

sendInvitationEmail: bool - Whether to send an invitation email for the created user

client.User().DeleteUser(ctx, userId) -> error

📝 Description

Deletes a user by user ID.

🔌 Usage

if err := client.User().DeleteUser(ctx, "usr_123"); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

userId: string

client.User().CreateMembership(ctx, organizationId, userId, membership, sendInvitationEmail) -> (*CreateMembershipResponse, error)

📝 Description

Creates a membership for an existing user in an organization.

🔌 Usage

resp, err := client.User().CreateMembership(ctx, "org_123", "usr_123", &users.CreateMembership{
  Roles: []*commons.Role{{Name: "admin"}},
  Metadata: map[string]string{
    "membership_type": "test",
  },
}, false)
if err != nil {
  // handle
}
_ = resp.User

⚙️ Parameters

ctx: context.Context

organizationId: string

userId: string

membership: *usersv1.CreateMembership

sendInvitationEmail: bool

client.User().UpdateMembership(ctx, organizationId, userId, membership) -> (*UpdateMembershipResponse, error)

📝 Description

Updates a membership for a user within an organization.

🔌 Usage

resp, err := client.User().UpdateMembership(ctx, "org_123", "usr_123", &users.UpdateMembership{
  Roles: []*commons.Role{{Name: "member"}},
})
if err != nil {
  // handle
}
_ = resp.User

⚙️ Parameters

ctx: context.Context

organizationId: string

userId: string

membership: *usersv1.UpdateMembership

client.User().DeleteMembership(ctx, organizationId, userId, cascade) -> error

📝 Description

Deletes a membership for a user from an organization.

If cascade is true, the API may also delete related resources (behavior depends on backend).

🔌 Usage

if err := client.User().DeleteMembership(ctx, "org_123", "usr_123", false); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

organizationId: string

userId: string

cascade: bool

client.User().ResendInvite(ctx, organizationId, userId) -> (*usersv1.ResendInviteResponse, error)

📝 Description

Resends a pending invite for a user in an organization.

🔌 Usage

resp, err := client.User().ResendInvite(ctx, "org_123", "usr_123")
if err != nil {
  // handle
}
_ = resp.Invite

⚙️ Parameters

ctx: context.Context

organizationId: string

userId: string

Domains

client.Domain().CreateDomain(ctx, organizationId, name, options?) -> (*CreateDomainResponse, error)

📝 Description

Creates a domain for an organization.

The SDK supports backward-compatible signatures:

• CreateDomain(ctx, orgId, domain) (no options)
• CreateDomain(ctx, orgId, domain, options) (with options)

🔌 Usage

// Without options (backward compatible)
created, err := client.Domain().CreateDomain(ctx, "org_123", "acme.com")
if err != nil {
  // handle
}
_ = created.Domain

// With options
created2, err := client.Domain().CreateDomain(ctx, "org_123", "acme.com", &scalekit.CreateDomainOptions{
  DomainType: scalekit.DomainTypeOrganization,
})
if err != nil {
  // handle
}
_ = created2.Domain

⚙️ Parameters

ctx: context.Context

organizationId: string

name: string - Domain name (e.g. acme.com)

options?: *CreateDomainOptions

• DomainType DomainType - DOMAIN_TYPE_UNSPECIFIED, ALLOWED_EMAIL_DOMAIN, or ORGANIZATION_DOMAIN

client.Domain().GetDomain(ctx, id, organizationId) -> (*GetDomainResponse, error)

📝 Description

Fetches a domain by ID within an organization.

🔌 Usage

domain, err := client.Domain().GetDomain(ctx, "dom_123", "org_123")
if err != nil {
  // handle
}
_ = domain.Domain

⚙️ Parameters

ctx: context.Context

id: string - Domain ID

organizationId: string

client.Domain().ListDomains(ctx, organizationId, options?) -> (*ListDomainResponse, error)

📝 Description

Lists domains for an organization (supports optional filtering and pagination).

🔌 Usage

// List all domains
all, err := client.Domain().ListDomains(ctx, "org_123")
if err != nil {
  // handle
}
_ = all.Domains

// Filter by domain type
orgDomains, err := client.Domain().ListDomains(ctx, "org_123", &scalekit.ListDomainOptions{
  DomainType: scalekit.DomainTypeOrganization,
})
if err != nil {
  // handle
}
_ = orgDomains.Domains

⚙️ Parameters

ctx: context.Context

organizationId: string

options?: *ListDomainOptions

• DomainType DomainType
• PageSize uint32
• PageNumber uint32

client.Domain().DeleteDomain(ctx, id, organizationId) -> error

📝 Description

Deletes a domain by ID within an organization.

🔌 Usage

if err := client.Domain().DeleteDomain(ctx, "dom_123", "org_123"); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

id: string

organizationId: string

Directories

client.Directory().CreateDirectory(ctx, organizationId, directory) -> (*CreateDirectoryResponse, error)

📝 Description

Creates a directory for an organization.

🔌 Usage

import (
  directoriesv1 "github.com/scalekit-inc/scalekit-sdk-go/v2/pkg/grpc/scalekit/v1/directories"
)

created, err := client.Directory().CreateDirectory(ctx, "org_123", &directoriesv1.CreateDirectory{
  DirectoryType:     directoriesv1.DirectoryType_SCIM,
  DirectoryProvider: directoriesv1.DirectoryProvider_OKTA,
})
if err != nil {
  // handle
}
_ = created.Directory

⚙️ Parameters

ctx: context.Context

organizationId: string - Organization ID

directory: *directoriesv1.CreateDirectory

client.Directory().DeleteDirectory(ctx, organizationId, directoryId) -> error

📝 Description

Deletes a directory by ID within an organization.

🔌 Usage

if err := client.Directory().DeleteDirectory(ctx, "org_123", "dir_456"); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

organizationId: string - Organization ID

directoryId: string - Directory ID

client.Directory().ListDirectories(ctx, organizationId) -> (*ListDirectoriesResponse, error)

📝 Description

Lists directories for an organization.

🔌 Usage

dirs, err := client.Directory().ListDirectories(ctx, "org_123")
if err != nil {
  // handle
}
_ = dirs.Directories

⚙️ Parameters

ctx: context.Context

organizationId: string

client.Directory().GetDirectory(ctx, organizationId, directoryId) -> (*GetDirectoryResponse, error)

📝 Description

Fetches a directory by ID within an organization.

🔌 Usage

dir, err := client.Directory().GetDirectory(ctx, "org_123", "dir_123")
if err != nil {
  // handle
}
_ = dir.Directory

⚙️ Parameters

ctx: context.Context

organizationId: string

directoryId: string

client.Directory().GetPrimaryDirectoryByOrganizationId(ctx, organizationId) -> (*GetDirectoryResponse, error)

📝 Description

Convenience helper to return the first directory for an organization (if any).

🔌 Usage

dir, err := client.Directory().GetPrimaryDirectoryByOrganizationId(ctx, "org_123")
if err != nil {
  // handle
}
_ = dir.Directory

⚙️ Parameters

ctx: context.Context

organizationId: string

client.Directory().ListDirectoryUsers(ctx, organizationId, directoryId, options?) -> (*ListDirectoryUsersResponse, error)

📝 Description

Lists users from a directory (paginated). Supports optional UpdatedAfter, group filtering, and detail inclusion.

🔌 Usage

includeDetail := true
updatedAfter := time.Unix(1729851960, 0)

resp, err := client.Directory().ListDirectoryUsers(ctx, "org_123", "dir_123", &scalekit.ListDirectoryUsersOptions{
  PageSize:      10,
  PageToken:     "",
  IncludeDetail: &includeDetail,
  UpdatedAfter:  &updatedAfter,
})
if err != nil {
  // handle
}
_ = resp.Users

⚙️ Parameters

ctx: context.Context

organizationId: string

directoryId: string

options?: *ListDirectoryUsersOptions

• PageSize uint32
• PageToken string
• IncludeDetail *bool
• DirectoryGroupId *string
• UpdatedAfter *time.Time

client.Directory().ListDirectoryGroups(ctx, organizationId, directoryId, options?) -> (*ListDirectoryGroupsResponse, error)

📝 Description

Lists groups from a directory (paginated).

🔌 Usage

includeDetail := true
resp, err := client.Directory().ListDirectoryGroups(ctx, "org_123", "dir_123", &scalekit.ListDirectoryGroupsOptions{
  PageSize:      10,
  PageToken:     "",
  IncludeDetail: &includeDetail,
})
if err != nil {
  // handle
}
_ = resp.Groups

⚙️ Parameters

ctx: context.Context

organizationId: string

directoryId: string

options?: *ListDirectoryGroupsOptions

• PageSize uint32
• PageToken string
• IncludeDetail *bool
• UpdatedAfter *time.Time

client.Directory().EnableDirectory(ctx, organizationId, directoryId) -> (*ToggleDirectoryResponse, error)

📝 Description

Enables a directory for an organization.

🔌 Usage

resp, err := client.Directory().EnableDirectory(ctx, "org_123", "dir_123")
if err != nil {
  // handle
}
_ = resp.Enabled

⚙️ Parameters

ctx: context.Context

organizationId: string

directoryId: string

client.Directory().DisableDirectory(ctx, organizationId, directoryId) -> (*ToggleDirectoryResponse, error)

📝 Description

Disables a directory for an organization.

🔌 Usage

resp, err := client.Directory().DisableDirectory(ctx, "org_123", "dir_123")
if err != nil {
  // handle
}
_ = resp.Enabled

⚙️ Parameters

ctx: context.Context

organizationId: string

directoryId: string

Sessions

client.Session().GetSession(ctx, sessionId) -> (*SessionDetails, error)

📝 Description

Fetches session details by session ID.

🔌 Usage

session, err := client.Session().GetSession(ctx, "ses_123")
if err != nil {
  // handle
}
_ = session

⚙️ Parameters

ctx: context.Context

sessionId: string

client.Session().GetUserSessions(ctx, userId, pageSize, pageToken, filter?) -> (*UserSessionDetails, error)

📝 Description

Lists session details for a user (paginated).

🔌 Usage

resp, err := client.Session().GetUserSessions(ctx, "usr_123", 10, "", nil)
if err != nil {
  // handle
}
_ = resp.Sessions

⚙️ Parameters

ctx: context.Context

userId: string

pageSize: uint32

pageToken: string

filter?: *sessionsv1.UserSessionFilter

client.Session().RevokeSession(ctx, sessionId) -> (*RevokeSessionResponse, error)

📝 Description

Revokes a specific session by session ID.

🔌 Usage

resp, err := client.Session().RevokeSession(ctx, "ses_123")
if err != nil {
  // handle
}
_ = resp

⚙️ Parameters

ctx: context.Context

sessionId: string

client.Session().RevokeAllUserSessions(ctx, userId) -> (*RevokeAllUserSessionsResponse, error)

📝 Description

Revokes all sessions for a user.

🔌 Usage

resp, err := client.Session().RevokeAllUserSessions(ctx, "usr_123")
if err != nil {
  // handle
}
_ = resp

⚙️ Parameters

ctx: context.Context

userId: string

API Tokens

client.Token().CreateToken(ctx, organizationId, options) -> (*CreateTokenResponse, error)

📝 Description

Creates a new API token for an organization with optional custom claims and expiration.

🔌 Usage

expiry := time.Now().Add(24 * time.Hour)
resp, err := client.Token().CreateToken(ctx, "org_123", scalekit.CreateTokenOptions{
  UserId:       "usr_123",
  Description:  "Service account token",
  CustomClaims: map[string]string{
    "source": "service",
  },
  Expiry:       &expiry,
})
if err != nil {
  // handle
}
_ = resp.Token

⚙️ Parameters

ctx: context.Context

organizationId: string - Organization ID to create token for

options: CreateTokenOptions

• UserId string - Optional: user ID to associate with token
• CustomClaims map[string]string - Optional: custom claims to embed in token
• Expiry *time.Time - Optional: token expiration time
• Description string - Optional: token description

client.Token().ValidateToken(ctx, token) -> (*ValidateTokenResponse, error)

📝 Description

Validates an API token and returns token information if valid.

🔌 Usage

resp, err := client.Token().ValidateToken(ctx, "api_token_here")
if err != nil {
  // token is invalid or expired
}
_ = resp.Token

⚙️ Parameters

ctx: context.Context

token: string - API token to validate

client.Token().InvalidateToken(ctx, token) -> error

📝 Description

Invalidates (revokes) an API token immediately.

🔌 Usage

if err := client.Token().InvalidateToken(ctx, "api_token_here"); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

token: string - API token to invalidate

client.Token().ListTokens(ctx, organizationId, options) -> (*ListTokensResponse, error)

📝 Description

Lists API tokens for an organization with optional filtering and pagination.

🔌 Usage

// List all tokens
tokens, err := client.Token().ListTokens(ctx, "org_123", scalekit.ListTokensOptions{})
if err != nil {
  // handle
}
for _, token := range tokens.Tokens {
  _ = token
}

// Filter by user ID
userTokens, err := client.Token().ListTokens(ctx, "org_123", scalekit.ListTokensOptions{
  UserId: "usr_123",
})

⚙️ Parameters

ctx: context.Context

organizationId: string - Organization ID to list tokens for

options: ListTokensOptions

• UserId string - Optional: filter tokens by user ID
• PageSize int32 - Optional: number of results per page
• PageToken string - Optional: pagination token from previous response

Roles

client.Role().CreateRole(ctx, role) -> (*CreateRoleResponse, error)

📝 Description

Creates a new environment-level role.

⚙️ Parameters

ctx: context.Context

role: *rolesv1.CreateRole

client.Role().GetRole(ctx, roleName) -> (*GetRoleResponse, error)

📝 Description

Fetches an environment-level role by name.

⚙️ Parameters

ctx: context.Context

roleName: string

client.Role().ListRoles(ctx) -> (*ListRolesResponse, error)

📝 Description

Lists all environment-level roles.

⚙️ Parameters

ctx: context.Context

client.Role().UpdateRole(ctx, roleName, role) -> (*UpdateRoleResponse, error)

📝 Description

Updates an environment-level role.

⚙️ Parameters

ctx: context.Context

roleName: string

role: *rolesv1.UpdateRole

client.Role().DeleteRole(ctx, roleName, reassignRoleName?) -> error

📝 Description

Deletes an environment-level role. Optionally provide reassignRoleName to reassign users.

⚙️ Parameters

ctx: context.Context

roleName: string

reassignRoleName?: string

client.Role().GetRoleUsersCount(ctx, roleName) -> (*GetRoleUsersCountResponse, error)

📝 Description

Gets the count of users associated with an environment-level role.

⚙️ Parameters

ctx: context.Context

roleName: string

client.Role().CreateOrganizationRole(ctx, orgId, role) -> (*CreateOrganizationRoleResponse, error)

📝 Description

Creates an organization-level role.

⚙️ Parameters

ctx: context.Context

orgId: string

role: *rolesv1.CreateOrganizationRole

client.Role().GetOrganizationRole(ctx, orgId, roleName) -> (*GetOrganizationRoleResponse, error)

📝 Description

Fetches an organization-level role by name.

⚙️ Parameters

ctx: context.Context

orgId: string

roleName: string

client.Role().ListOrganizationRoles(ctx, orgId) -> (*ListOrganizationRolesResponse, error)

📝 Description

Lists organization-level roles.

⚙️ Parameters

ctx: context.Context

orgId: string

client.Role().UpdateOrganizationRole(ctx, orgId, roleName, role) -> (*UpdateOrganizationRoleResponse, error)

📝 Description

Updates an organization-level role by name.

⚙️ Parameters

ctx: context.Context

orgId: string

roleName: string

role: *rolesv1.UpdateRole

client.Role().DeleteOrganizationRole(ctx, orgId, roleName, reassignRoleName?) -> error

📝 Description

Deletes an organization-level role by name. Optionally provide reassignRoleName.

⚙️ Parameters

ctx: context.Context

orgId: string

roleName: string

reassignRoleName?: string

client.Role().GetOrganizationRoleUsersCount(ctx, orgId, roleName) -> (*GetOrganizationRoleUsersCountResponse, error)

📝 Description

Gets the count of users associated with an organization-level role.

⚙️ Parameters

ctx: context.Context

orgId: string

roleName: string

client.Role().UpdateDefaultOrganizationRoles(ctx, orgId, defaultMemberRole) -> (*UpdateDefaultOrganizationRolesResponse, error)

📝 Description

Updates the default member role for an organization.

⚙️ Parameters

ctx: context.Context

orgId: string

defaultMemberRole: string

client.Role().DeleteOrganizationRoleBase(ctx, orgId, roleName) -> error

📝 Description

Deletes the base relationship for an organization role.

⚙️ Parameters

ctx: context.Context

orgId: string

roleName: string

Permissions

client.Permission().CreatePermission(ctx, permission) -> (*CreatePermissionResponse, error)

📝 Description

Creates a new permission.

⚙️ Parameters

ctx: context.Context

permission: *rolesv1.CreatePermission

client.Permission().GetPermission(ctx, permissionName) -> (*GetPermissionResponse, error)

📝 Description

Fetches a permission by name.

⚙️ Parameters

ctx: context.Context

permissionName: string

client.Permission().ListPermissions(ctx, pageToken?) -> (*ListPermissionsResponse, error)

📝 Description

Lists permissions with optional pagination.

⚙️ Parameters

ctx: context.Context

pageToken?: string

client.Permission().UpdatePermission(ctx, permissionName, permission) -> (*UpdatePermissionResponse, error)

📝 Description

Updates an existing permission by name.

⚙️ Parameters

ctx: context.Context

permissionName: string

permission: *rolesv1.CreatePermission

client.Permission().DeletePermission(ctx, permissionName) -> error

📝 Description

Deletes a permission by name.

⚙️ Parameters

ctx: context.Context

permissionName: string

client.Permission().ListRolePermissions(ctx, roleName) -> (*ListRolePermissionsResponse, error)

📝 Description

Lists permissions associated with a role.

⚙️ Parameters

ctx: context.Context

roleName: string

client.Permission().AddPermissionsToRole(ctx, roleName, permissionNames) -> (*AddPermissionsToRoleResponse, error)

📝 Description

Adds permissions to a role.

⚙️ Parameters

ctx: context.Context

roleName: string

permissionNames: []string

client.Permission().RemovePermissionFromRole(ctx, roleName, permissionName) -> error

📝 Description

Removes a permission from a role.

⚙️ Parameters

ctx: context.Context

roleName: string

permissionName: string

client.Permission().ListEffectiveRolePermissions(ctx, roleName) -> (*ListEffectiveRolePermissionsResponse, error)

📝 Description

Lists effective permissions for a role (including inherited permissions).

⚙️ Parameters

ctx: context.Context

roleName: string

Passwordless

client.Passwordless().SendPasswordlessEmail(ctx, email, options?) -> (*SendPasswordlessResponse, error)

📝 Description

Sends a passwordless authentication email (OTP, magic link, etc. depending on configuration).

🔌 Usage

template := scalekit.TemplateTypeSignin
resp, err := client.Passwordless().SendPasswordlessEmail(ctx, "user@example.com", &scalekit.SendPasswordlessOptions{
  Template:         &template,
  MagiclinkAuthUri: "https://myapp.com/auth/callback",
  State:            "state",
  ExpiresIn:        1800,
  TemplateVariables: map[string]string{
    "app_name": "My App",
  },
})
if err != nil {
  // handle
}
_ = resp.AuthRequestId

⚙️ Parameters

ctx: context.Context

email: string

options?: *SendPasswordlessOptions

• Template *TemplateType (SIGNIN, SIGNUP)
• MagiclinkAuthUri string
• State string
• ExpiresIn uint32
• TemplateVariables map[string]string

client.Passwordless().VerifyPasswordlessEmail(ctx, options) -> (*VerifyPasswordLessResponse, error)

📝 Description

Verifies a passwordless authentication attempt using an OTP code or link token.

🔌 Usage

verified, err := client.Passwordless().VerifyPasswordlessEmail(ctx, &scalekit.VerifyPasswordlessOptions{
  Code:          "123456",
  AuthRequestId: "auth_req_123",
})
if err != nil {
  // handle
}
_ = verified

⚙️ Parameters

ctx: context.Context

options: *VerifyPasswordlessOptions

• Code string - OTP code
• LinkToken string - Magic link token
• AuthRequestId string - Required in some flows

client.Passwordless().ResendPasswordlessEmail(ctx, authRequestId) -> (*SendPasswordlessResponse, error)

📝 Description

Resends a passwordless authentication email for an existing auth request.

🔌 Usage

resp, err := client.Passwordless().ResendPasswordlessEmail(ctx, "auth_req_123")
if err != nil {
  // handle
}
_ = resp.AuthRequestId

⚙️ Parameters

ctx: context.Context

authRequestId: string

WebAuthn

client.WebAuthn().ListCredentials(ctx, userId) -> (*ListCredentialsResponse, error)

📝 Description

Lists passkey credentials for a user. If userId is empty, the API may list credentials for the current authenticated user.

⚙️ Parameters

ctx: context.Context

userId: string

client.WebAuthn().UpdateCredential(ctx, credentialId, displayName) -> (*UpdateCredentialResponse, error)

📝 Description

Updates the display name of a passkey credential.

⚙️ Parameters

ctx: context.Context

credentialId: string

displayName: string

client.WebAuthn().DeleteCredential(ctx, credentialId) -> (*DeleteCredentialResponse, error)

📝 Description

Deletes a passkey credential by credential ID.

⚙️ Parameters

ctx: context.Context

credentialId: string

Auth

client.Auth().UpdateLoginUserDetails(ctx, req) -> error

📝 Description

Updates login user details associated with an authentication flow.

This method uses the Auth gRPC surface and expects a fully populated request.

🔌 Usage

req := &scalekit.UpdateLoginUserDetailsRequest{
  ConnectionId:   "conn_123",
  LoginRequestId: "login_req_123",
  User: &scalekit.LoggedInUserDetails{
    Sub:   "sub",
    Email: "user@example.com",
  },
}

if err := client.Auth().UpdateLoginUserDetails(ctx, req); err != nil {
  // handle
}

⚙️ Parameters

ctx: context.Context

req: *UpdateLoginUserDetailsRequest

Source: View on GitHub →

Last fetched: April 1, 2026