diff --git a/REFERENCE.mdx b/REFERENCE.mdx new file mode 100644 index 0000000..1d472a1 --- /dev/null +++ b/REFERENCE.mdx @@ -0,0 +1,696 @@ +# Scalekit SDK for Go - API Reference + +## Client Initialization + +```go +import "github.com/scalekit-inc/scalekit-sdk-go" + +// Initialize the Scalekit client +client := scalekit.NewScalekitClient(envUrl, clientId, clientSecret) +``` + +## Core API + +The main `Scalekit` interface provides several methods for authentication and token validation: + +### GetAuthorizationUrl + +Generates an authorization URL for OAuth 2.0 flows. + +```go +func (s *Scalekit) GetAuthorizationUrl(redirectUri string, options AuthorizationUrlOptions) (*url.URL, error) +``` + +**Parameters:** +- `redirectUri` (string): The URI to redirect to after authorization +- `options` (AuthorizationUrlOptions): Configuration options including: + - `ConnectionId` (string): Optional connection ID + - `OrganizationId` (string): Optional organization ID + - `Scopes` ([]string): OAuth scopes (defaults to ["openid", "profile", "email"]) + - `State` (string): OAuth state parameter + - `Nonce` (string): OAuth nonce parameter + - `DomainHint` (string): Domain hint for authentication + - `LoginHint` (string): Login hint parameter + - `CodeChallenge` (string): PKCE code challenge + - `CodeChallengeMethod` (string): PKCE code challenge method + - `Provider` (string): Identity provider + +**Returns:** +- `*url.URL`: The authorization URL +- `error`: Any error that occurred + +### AuthenticateWithCode + +Exchanges an authorization code for tokens. + +```go +func (s *Scalekit) AuthenticateWithCode(code string, redirectUri string, options AuthenticationOptions) (*AuthenticationResponse, error) +``` + +**Parameters:** +- `code` (string): The authorization code received from the authorization server +- `redirectUri` (string): The redirect URI used in the authorization request +- `options` (AuthenticationOptions): Options including: + - `CodeVerifier` (string): PKCE code verifier + +**Returns:** +- `*AuthenticationResponse`: Response containing: + - `User` (User): User profile information + - `IdToken` (string): ID token + - `AccessToken` (string): Access token + - `ExpiresIn` (int): Token expiration time in seconds +- `error`: Any error that occurred + +### GetIdpInitiatedLoginClaims + +Validates and retrieves claims from an IdP-initiated login token. + +```go +func (s *Scalekit) GetIdpInitiatedLoginClaims(idpInitiateLoginToken string) (*IdpInitiatedLoginClaims, error) +``` + +**Parameters:** +- `idpInitiateLoginToken` (string): The token received from an IdP-initiated login + +**Returns:** +- `*IdpInitiatedLoginClaims`: Claims from the token including: + - `ConnectionID` (string): Connection ID + - `OrganizationID` (string): Organization ID + - `LoginHint` (string): Login hint + - `RelayState` (*string): Optional relay state +- `error`: Any error that occurred + +### ValidateAccessToken + +Validates an access token. + +```go +func (s *Scalekit) ValidateAccessToken(accessToken string) (bool, error) +``` + +**Parameters:** +- `accessToken` (string): The access token to validate + +**Returns:** +- `bool`: True if the token is valid +- `error`: Any error that occurred + +### VerifyWebhookPayload + +Verifies the signature of a webhook payload. + +```go +func (s *Scalekit) VerifyWebhookPayload(secret string, headers map[string]string, payload []byte) (bool, error) +``` + +**Parameters:** +- `secret` (string): Webhook secret +- `headers` (map[string]string): HTTP headers from the webhook request +- `payload` ([]byte): Raw webhook payload body + +**Returns:** +- `bool`: True if the payload signature is valid +- `error`: Any error that occurred + +## Connection API + +The Connection API provides methods to manage connections. + +```go +// Access Connection API +connectionClient := client.Connection() +``` + +### GetConnection + +Gets details of a specific connection. + +```go +func (c *Connection) GetConnection(ctx context.Context, organizationId string, id string) (*GetConnectionResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID +- `id` (string): Connection ID + +**Returns:** +- `*GetConnectionResponse`: Connection details +- `error`: Any error that occurred + +### ListConnectionsByDomain + +Lists connections associated with a domain. + +```go +func (c *Connection) ListConnectionsByDomain(ctx context.Context, domain string) (*ListConnectionsResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `domain` (string): Domain name + +**Returns:** +- `*ListConnectionsResponse`: List of connections +- `error`: Any error that occurred + +### ListConnections + +Lists connections for an organization. + +```go +func (c *Connection) ListConnections(ctx context.Context, organizationId string) (*ListConnectionsResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID + +**Returns:** +- `*ListConnectionsResponse`: List of connections +- `error`: Any error that occurred + +### EnableConnection + +Enables a connection. + +```go +func (c *Connection) EnableConnection(ctx context.Context, organizationId string, id string) (*ToggleConnectionResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID +- `id` (string): Connection ID + +**Returns:** +- `*ToggleConnectionResponse`: Updated connection details +- `error`: Any error that occurred + +### DisableConnection + +Disables a connection. + +```go +func (c *Connection) DisableConnection(ctx context.Context, organizationId string, id string) (*ToggleConnectionResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID +- `id` (string): Connection ID + +**Returns:** +- `*ToggleConnectionResponse`: Updated connection details +- `error`: Any error that occurred + +## Directory API + +The Directory API provides methods to manage directories and users. + +```go +// Access Directory API +directoryClient := client.Directory() +``` + +### ListDirectories + +Lists directories for an organization. + +```go +func (d *Directory) ListDirectories(ctx context.Context, organizationId string) (*ListDirectoriesResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID + +**Returns:** +- `*ListDirectoriesResponse`: List of directories +- `error`: Any error that occurred + +### GetDirectory + +Gets details of a specific directory. + +```go +func (d *Directory) GetDirectory(ctx context.Context, organizationId string, directoryId string) (*GetDirectoryResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID +- `directoryId` (string): Directory ID + +**Returns:** +- `*GetDirectoryResponse`: Directory details +- `error`: Any error that occurred + +### ListDirectoryUsers + +Lists users in a directory. + +```go +func (d *Directory) ListDirectoryUsers(ctx context.Context, organizationId string, directoryId string, options *ListDirectoryUsersOptions) (*ListDirectoryUsersResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID +- `directoryId` (string): Directory ID +- `options` (*ListDirectoryUsersOptions): Query options including: + - `PageSize` (uint32): Number of results per page + - `PageToken` (string): Token for pagination + - `IncludeDetail` (*bool): Whether to include detailed information + - `DirectoryGroupId` (*string): Filter by directory group ID + - `UpdatedAfter` (*time.Time): Filter by update timestamp + +**Returns:** +- `*ListDirectoryUsersResponse`: List of users +- `error`: Any error that occurred + +### ListDirectoryGroups + +Lists groups in a directory. + +```go +func (d *Directory) ListDirectoryGroups(ctx context.Context, organizationId string, directoryId string, options *ListDirectoryGroupsOptions) (*ListDirectoryGroupsResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID +- `directoryId` (string): Directory ID +- `options` (*ListDirectoryGroupsOptions): Query options including: + - `PageSize` (uint32): Number of results per page + - `PageToken` (string): Token for pagination + - `IncludeDetail` (*bool): Whether to include detailed information + - `UpdatedAfter` (*time.Time): Filter by update timestamp + +**Returns:** +- `*ListDirectoryGroupsResponse`: List of groups +- `error`: Any error that occurred + +### GetPrimaryDirectoryByOrganizationId + +Gets the primary directory for an organization. + +```go +func (d *Directory) GetPrimaryDirectoryByOrganizationId(ctx context.Context, organizationId string) (*GetDirectoryResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID + +**Returns:** +- `*GetDirectoryResponse`: Primary directory details +- `error`: Any error that occurred + +### EnableDirectory + +Enables a directory. + +```go +func (d *Directory) EnableDirectory(ctx context.Context, organizationId string, directoryId string) (*ToggleDirectoryResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID +- `directoryId` (string): Directory ID + +**Returns:** +- `*ToggleDirectoryResponse`: Updated directory details +- `error`: Any error that occurred + +### DisableDirectory + +Disables a directory. + +```go +func (d *Directory) DisableDirectory(ctx context.Context, organizationId string, directoryId string) (*ToggleDirectoryResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID +- `directoryId` (string): Directory ID + +**Returns:** +- `*ToggleDirectoryResponse`: Updated directory details +- `error`: Any error that occurred + +## Domain API + +The Domain API provides methods to manage domains. + +```go +// Access Domain API +domainClient := client.Domain() +``` + +### CreateDomain + +Creates a new domain. + +```go +func (d *Domain) CreateDomain(ctx context.Context, organizationId, name string) (*CreateDomainResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID +- `name` (string): Domain name + +**Returns:** +- `*CreateDomainResponse`: Created domain details +- `error`: Any error that occurred + +### GetDomain + +Gets details of a specific domain. + +```go +func (d *Domain) GetDomain(ctx context.Context, id string, organizationId string) (*GetDomainResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `id` (string): Domain ID +- `organizationId` (string): Organization ID + +**Returns:** +- `*GetDomainResponse`: Domain details +- `error`: Any error that occurred + +### ListDomains + +Lists domains for an organization. + +```go +func (d *Domain) ListDomains(ctx context.Context, organizationId string) (*ListDomainResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID + +**Returns:** +- `*ListDomainResponse`: List of domains +- `error`: Any error that occurred + +## Organization API + +The Organization API provides methods to manage organizations. + +```go +// Access Organization API +organizationClient := client.Organization() +``` + +### CreateOrganization + +Creates a new organization. + +```go +func (o *Organization) CreateOrganization(ctx context.Context, name string, options CreateOrganizationOptions) (*CreateOrganizationResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `name` (string): Organization name +- `options` (CreateOrganizationOptions): Options including: + - `ExternalId` (string): External ID for the organization + - `Metadata` (map[string]string): Metadata key-value pairs + +**Returns:** +- `*CreateOrganizationResponse`: Created organization details +- `error`: Any error that occurred + +### ListOrganization + +Lists organizations. + +```go +func (o *Organization) ListOrganization(ctx context.Context, options *ListOrganizationOptions) (*ListOrganizationsResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `options` (*ListOrganizationOptions): Query options including: + - `PageSize` (uint32): Number of results per page + - `PageToken` (string): Token for pagination + +**Returns:** +- `*ListOrganizationsResponse`: List of organizations +- `error`: Any error that occurred + +### GetOrganization + +Gets details of a specific organization. + +```go +func (o *Organization) GetOrganization(ctx context.Context, id string) (*GetOrganizationResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `id` (string): Organization ID + +**Returns:** +- `*GetOrganizationResponse`: Organization details +- `error`: Any error that occurred + +### GetOrganizationByExternalId + +Gets an organization by its external ID. + +```go +func (o *Organization) GetOrganizationByExternalId(ctx context.Context, externalId string) (*GetOrganizationResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `externalId` (string): External ID + +**Returns:** +- `*GetOrganizationResponse`: Organization details +- `error`: Any error that occurred + +### UpdateOrganization + +Updates an organization. + +```go +func (o *Organization) UpdateOrganization(ctx context.Context, id string, organization *UpdateOrganization) (*UpdateOrganizationResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `id` (string): Organization ID +- `organization` (*UpdateOrganization): Updated organization data + +**Returns:** +- `*UpdateOrganizationResponse`: Updated organization details +- `error`: Any error that occurred + +### UpdateOrganizationByExternalId + +Updates an organization by its external ID. + +```go +func (o *Organization) UpdateOrganizationByExternalId(ctx context.Context, externalId string, organization *UpdateOrganization) (*UpdateOrganizationResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `externalId` (string): External ID +- `organization` (*UpdateOrganization): Updated organization data + +**Returns:** +- `*UpdateOrganizationResponse`: Updated organization details +- `error`: Any error that occurred + +### DeleteOrganization + +Deletes an organization. + +```go +func (o *Organization) DeleteOrganization(ctx context.Context, id string) error +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `id` (string): Organization ID + +**Returns:** +- `error`: Any error that occurred + +### GeneratePortalLink + +Generates a management portal link for an organization. + +```go +func (o *Organization) GeneratePortalLink(ctx context.Context, organizationId string) (*Link, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `organizationId` (string): Organization ID + +**Returns:** +- `*Link`: Portal link information +- `error`: Any error that occurred + +### UpdateOrganizationSettings + +Updates organization settings. + +```go +func (o *Organization) UpdateOrganizationSettings(ctx context.Context, id string, settings OrganizationSettings) (*GetOrganizationResponse, error) +``` + +**Parameters:** +- `ctx` (context.Context): Context for the request +- `id` (string): Organization ID +- `settings` (OrganizationSettings): Settings including: + - `Features` ([]Feature): List of features to update, each with: + - `Name` (string): Feature name + - `Enabled` (bool): Feature enabled state + +**Returns:** +- `*GetOrganizationResponse`: Updated organization details +- `error`: Any error that occurred + +## Data Types + +### AuthorizationUrlOptions + +```go +type AuthorizationUrlOptions struct { + ConnectionId string + OrganizationId string + Scopes []string + State string + Nonce string + DomainHint string + LoginHint string + CodeChallenge string + CodeChallengeMethod string + Provider string +} +``` + +### AuthenticationOptions + +```go +type AuthenticationOptions struct { + CodeVerifier string +} +``` + +### AuthenticationResponse + +```go +type AuthenticationResponse struct { + User User + IdToken string + AccessToken string + ExpiresIn int +} +``` + +### User (IdTokenClaims) + +```go +type User struct { + Id string // sub + Username string // preferred_username + Name string // name + GivenName string // given_name + FamilyName string // family_name + Email string // email + EmailVerified bool // email_verified + PhoneNumber string // phone_number + PhoneNumberVerified bool // phone_number_verified + Profile string // profile + Picture string // picture + Gender string // gender + BirthDate string // birthdate + ZoneInfo string // zoneinfo + Locale string // locale + UpdatedAt string // updated_at + Identities []Identity // identities + Metadata string // metadata +} +``` + +### Identity + +```go +type Identity struct { + ConnectionId string // connection_id + OrganizationId string // organization_id + ConnectionType string // connection_type + ProviderName string // provider_name + Social bool // social + ProviderRawAttributes string // provider_raw_attributes +} +``` + +### IdpInitiatedLoginClaims + +```go +type IdpInitiatedLoginClaims struct { + ConnectionID string + OrganizationID string + LoginHint string + RelayState *string +} +``` + +### ListDirectoryUsersOptions + +```go +type ListDirectoryUsersOptions struct { + PageSize uint32 + PageToken string + IncludeDetail *bool + DirectoryGroupId *string + UpdatedAfter *time.Time +} +``` + +### ListDirectoryGroupsOptions + +```go +type ListDirectoryGroupsOptions struct { + PageSize uint32 + PageToken string + IncludeDetail *bool + UpdatedAfter *time.Time +} +``` + +### CreateOrganizationOptions + +```go +type CreateOrganizationOptions struct { + ExternalId string + Metadata map[string]string +} +``` + +### OrganizationSettings + +```go +type OrganizationSettings struct { + Features []Feature +} + +type Feature struct { + Name string + Enabled bool +} +``` \ No newline at end of file