users

package
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 11, 2023 License: MIT Imports: 10 Imported by: 0

README

users

Go Report Card

A go package to request WorkOS User Management API.

Install

go get -u github.com/workos/workos-go/v2/pkg/users

How it works

See the User Management integration guide.

Documentation

Overview

Package users provides a client wrapping the WorkOS User Management API.

Index

Constants

View Source
const ResponseLimit = 10

ResponseLimit is the default number of records to limit a response to.

Variables

View Source
var (
	// DefaultClient is the client used by User management methods
	DefaultClient = NewClient("")
)

Functions

func RevokeAllSessionsForUser

func RevokeAllSessionsForUser(
	ctx context.Context,
	opts RevokeAllSessionsForUserOpts,
) (bool, error)

RevokeAllSessionsForUser revokes all active sessions for the given user.

func RevokeSession

func RevokeSession(
	ctx context.Context,
	opts RevokeSessionOpts,
) (bool, error)

RevokeSession revokes a single session, invalidating the token for further verification requests.

func SetAPIKey

func SetAPIKey(apiKey string)

SetAPIKey configures the default client that is used by the User management methods It must be called before using those functions.

Types

type AddUserToOrganizationOpts

type AddUserToOrganizationOpts struct {
	User         string `json:"id"`
	Organization string `json:"organization_id"`
}

type AuthenticateUserWithMagicAuthOpts

type AuthenticateUserWithMagicAuthOpts struct {
	ClientID             string               `json:"client_id"`
	Code                 string               `json:"code"`
	MagicAuthChallengeID MagicAuthChallengeID `json:"magic_auth_challenge_id"`
	ExpiresIn            int                  `json:"expires_in,omitempty"`
	IPAddress            string               `json:"ip_address,omitempty"`
	UserAgent            string               `json:"user_agent,omitempty"`
}

type AuthenticateUserWithPasswordOpts

type AuthenticateUserWithPasswordOpts struct {
	Email        string `json:"email"`
	Password     string `json:"password"`
	IPAddress    string `json:"ip_address,omitempty"`
	UserAgent    string `json:"user_agent,omitempty"`
	StartSession bool   `json:"start_session,omitempty"`
	ExpiresIn    int    `json:"expires_in,omitempty"`
}

type AuthenticateUserWithTokenOpts

type AuthenticateUserWithTokenOpts struct {
	ClientID  string `json:"client_id"`
	Code      string `json:"code"`
	ExpiresIn int    `json:"expires_in,omitempty"`
	IPAddress string `json:"ip_address,omitempty"`
	UserAgent string `json:"user_agent,omitempty"`
}

type AuthenticationResponse

type AuthenticationResponse struct {
	Session Session `json:"session"`
	User    User    `json:"user"`
}

func AuthenticateUserWithMagicAuth

func AuthenticateUserWithMagicAuth(
	ctx context.Context,
	opts AuthenticateUserWithMagicAuthOpts,
) (AuthenticationResponse, error)

AuthenticateUserWithMagicAuth authenticates a user by verifying a one-time code sent to the user's email address by the Magic Auth Send Code endpoint.

func AuthenticateUserWithPassword

func AuthenticateUserWithPassword(
	ctx context.Context,
	opts AuthenticateUserWithPasswordOpts,
) (AuthenticationResponse, error)

AuthenticateUserWithPassword authenticates a user with email and password and optionally creates a session.

func AuthenticateUserWithToken

func AuthenticateUserWithToken(
	ctx context.Context,
	opts AuthenticateUserWithTokenOpts,
) (AuthenticationResponse, error)

AuthenticateUserWithToken authenticates an OAuth user or a managed SSO user that is logging in through SSO, and optionally creates a session.

type AuthorizedOrganization

type AuthorizedOrganization struct {
	Organization Organization `json:"organization"`
}

type ChallengeResponse

type ChallengeResponse struct {
	Token string `json:"token"`

	User User `json:"user"`
}

func CreateEmailVerificationChallenge

func CreateEmailVerificationChallenge(
	ctx context.Context,
	opts CreateEmailVerificationChallengeOpts,
) (ChallengeResponse, error)

CreateEmailVerificationChallenge creates an email verification challenge and emails verification token to user.

func CreatePasswordResetChallenge

func CreatePasswordResetChallenge(
	ctx context.Context,
	opts CreatePasswordResetChallengeOpts,
) (ChallengeResponse, error)

CreatePasswordResetChallenge creates a password reset challenge and emails a password reset link to an unmanaged user.

type Client

type Client struct {
	// The WorkOS api key. It can be found in
	// https://dashboard.workos.com/api-keys.
	//
	// REQUIRED.
	APIKey string

	// The http.Client that is used to send request to WorkOS.
	//
	// Defaults to http.Client.
	HTTPClient *http.Client

	// The endpoint to WorkOS API.
	//
	// Defaults to https://api.workos.com.
	Endpoint string

	// The function used to encode in JSON. Defaults to json.Marshal.
	JSONEncode func(v interface{}) ([]byte, error)
}

Client represents a client that fetch User Management data from WorkOS API.

func NewClient

func NewClient(apiKey string) *Client

func (*Client) AddUserToOrganization

func (c *Client) AddUserToOrganization(ctx context.Context, opts AddUserToOrganizationOpts) (User, error)

AddUserToOrganization adds an unmanaged user to an Organization

func (*Client) AuthenticateUserWithMagicAuth

func (c *Client) AuthenticateUserWithMagicAuth(ctx context.Context, opts AuthenticateUserWithMagicAuthOpts) (AuthenticationResponse, error)

AuthenticateUserWithMagicAuth authenticates a user by verifying a one-time code sent to the user's email address by the Magic Auth Send Code endpoint.

func (*Client) AuthenticateUserWithPassword

func (c *Client) AuthenticateUserWithPassword(ctx context.Context, opts AuthenticateUserWithPasswordOpts) (AuthenticationResponse, error)

func (*Client) AuthenticateUserWithToken

func (c *Client) AuthenticateUserWithToken(ctx context.Context, opts AuthenticateUserWithTokenOpts) (AuthenticationResponse, error)

AuthenticateUserWithToken authenticates an OAuth user or a managed SSO user that is logging in through SSO, and optionally creates a session.

func (*Client) CompleteEmailVerification

func (c *Client) CompleteEmailVerification(ctx context.Context, opts CompleteEmailVerificationOpts) (User, error)

CompleteEmailVerification verifies user email using verification token that was sent to the user.

func (*Client) CompletePasswordReset

func (c *Client) CompletePasswordReset(ctx context.Context, opts CompletePasswordResetOpts) (User, error)

CompletePasswordReset resets user password using token that was sent to the user.

func (*Client) CreateEmailVerificationChallenge

func (c *Client) CreateEmailVerificationChallenge(ctx context.Context, opts CreateEmailVerificationChallengeOpts) (ChallengeResponse, error)

CreateEmailVerificationChallenge creates an email verification challenge and emails verification token to user.

func (*Client) CreatePasswordResetChallenge

func (c *Client) CreatePasswordResetChallenge(ctx context.Context, opts CreatePasswordResetChallengeOpts) (ChallengeResponse, error)

CreatePasswordResetChallenge creates a password reset challenge and emails a password reset link to an unmanaged user.

func (*Client) CreateUser

func (c *Client) CreateUser(ctx context.Context, opts CreateUserOpts) (User, error)

CreateUser create a new user with email password authentication. Only unmanaged users can be created directly using the User Management API.

func (*Client) GetUser

func (c *Client) GetUser(ctx context.Context, opts GetUserOpts) (User, error)

GetUser returns details of an existing user

func (*Client) ListUsers

func (c *Client) ListUsers(ctx context.Context, opts ListUsersOpts) (ListUsersResponse, error)

ListUsers get a list of all of your existing users matching the criteria specified.

func (*Client) RemoveUserFromOrganization

func (c *Client) RemoveUserFromOrganization(ctx context.Context, opts RemoveUserFromOrganizationOpts) (User, error)

RemoveUserFromOrganization removes an unmanaged User from the given Organization.

func (*Client) RevokeAllSessionsForUser

func (c *Client) RevokeAllSessionsForUser(ctx context.Context, opts RevokeAllSessionsForUserOpts) (bool, error)

RevokeAllSessionsForUser revokes all active sessions for the given user.

func (*Client) RevokeSession

func (c *Client) RevokeSession(ctx context.Context, opts RevokeSessionOpts) (bool, error)

RevokeSession revokes a single session, invalidating the token for further verification requests. Either the session ID or token must be given to identify the session to revoke.

func (*Client) SendMagicAuthCode

func (c *Client) SendMagicAuthCode(ctx context.Context, opts SendMagicAuthCodeOpts) (MagicAuthChallengeID, error)

SendMagicAuthCode creates a one-time Magic Auth code and emails it to the user.

func (*Client) VerifySession

func (c *Client) VerifySession(ctx context.Context, opts VerifySessionOpts) (VerifySessionResponse, error)

VerifySession verifies the session token returned by the authentication request. If the token is authentic and has not expired the response will contain the authenticated user and session objects.

type CompleteEmailVerificationOpts

type CompleteEmailVerificationOpts struct {
	// The verification token emailed to the user.
	Token string `json:"token"`
}

type CompletePasswordResetOpts

type CompletePasswordResetOpts struct {
	// The verification token emailed to the user.
	Token string `json:"token"`

	// The new password to be set for the user.
	NewPassword string `json:"new_password"`
}

type CreateEmailVerificationChallengeOpts

type CreateEmailVerificationChallengeOpts struct {
	// The unique ID of the User whose email address will be verified.
	User string `json:"id"`

	// The URL that will be linked to in the verification email.
	VerificationUrl string `json:"verification_url"`
}

type CreatePasswordResetChallengeOpts

type CreatePasswordResetChallengeOpts struct {
	// The unique ID of the User whose email address will be verified.
	Email string `json:"email"`

	// The URL that will be linked to in the verification email.
	PasswordResetUrl string `json:"password_reset_url"`
}

type CreateUserOpts

type CreateUserOpts struct {
	Email         string `json:"email"`
	Password      string `json:"password,omitempty"`
	FirstName     string `json:"first_name,omitempty"`
	LastName      string `json:"last_name,omitempty"`
	EmailVerified bool   `json:"email_verified,omitempty"`
}

type GetUserOpts

type GetUserOpts struct {
	// User unique identifier
	User string `json:"id"`
}

GetUserOpts contains the options to pass in order to get a user profile.

type ListUsersOpts

type ListUsersOpts struct {
	// Filter Users by their type.
	Type UserType `url:"type,omitempty"`

	// Filter Users by their email.
	Email string `url:"email,omitempty"`

	// Filter Users by the organization they are members of.
	Organization string `url:"organization,omitempty"`

	// Maximum number of records to return.
	Limit int `url:"limit"`

	// The order in which to paginate records.
	Order Order `url:"order,omitempty"`

	// Pagination cursor to receive records before a provided User ID.
	Before string `url:"before,omitempty"`

	// Pagination cursor to receive records after a provided User ID.
	After string `url:"after,omitempty"`
}

type ListUsersResponse

type ListUsersResponse struct {
	// List of Users
	Data []User `json:"data"`

	// Cursor to paginate through the list of Users
	ListMetadata common.ListMetadata `json:"listMetadata"`
}

ListUsersResponse contains the response from the ListUsers call.

func ListUsers

func ListUsers(
	ctx context.Context,
	opts ListUsersOpts,
) (ListUsersResponse, error)

ListUsers gets a list of Users.

type MagicAuthChallenge

type MagicAuthChallenge struct {
	MagicAuthChallengeID MagicAuthChallengeID `json:"id"`
}

type MagicAuthChallengeID

type MagicAuthChallengeID string

func SendMagicAuthCode

func SendMagicAuthCode(
	ctx context.Context,
	opts SendMagicAuthCodeOpts,
) (MagicAuthChallengeID, error)

SendMagicAuthCode sends a one-time code to the user's email address.

type Order

type Order string

Order represents the order of records.

const (
	Asc  Order = "asc"
	Desc Order = "desc"
)

Constants that enumerate the available orders.

type Organization

type Organization struct {
	// The Organization's unique identifier.
	ID string `json:"id"`

	// The Organization's name.
	Name string `json:"name"`
}

Organization contains data about a particular Organization.

type OrganizationMembership

type OrganizationMembership struct {
	// Contains the ID and name of the associated Organization.
	Organization Organization `json:"organization"`

	// CreatedAt is the timestamp of when the OrganizationMembership was created.
	CreatedAt string `json:"created_at"`

	// UpdatedAt is the timestamp of when the OrganizationMembership was updated.
	UpdatedAt string `json:"updated_at"`
}

OrganizationMembership contains data about a particular OrganizationMembership.

type RemoveUserFromOrganizationOpts

type RemoveUserFromOrganizationOpts struct {
	User         string `json:"id"`
	Organization string `json:"organization_id"`
}

type RevokeAllSessionsForUserOpts

type RevokeAllSessionsForUserOpts struct {
	User string
}

type RevokeSessionOpts

type RevokeSessionOpts struct {
	SessionToken string `json:"session_token,omitempty"`
	SessionID    string `json:"session_id,omitempty"`
}

type SendMagicAuthCodeOpts

type SendMagicAuthCodeOpts struct {
	// The email address the one-time code will be sent to.
	Email string `json:"email_address"`
}

type Session

type Session struct {
	ID                        string                     `json:"id"`
	Token                     string                     `json:"token"`
	CreatedAt                 string                     `json:"created_at"`
	ExpiresAt                 string                     `json:"expires_at"`
	AuthorizedOrganizations   []AuthorizedOrganization   `json:"authorized_organizations"`
	UnauthorizedOrganizations []UnauthorizedOrganization `json:"unauthorized_organizations"`
}

type SessionAuthenticationMethod

type SessionAuthenticationMethod string
const (
	GoogleOauth    SessionAuthenticationMethod = "GoogleOauth"
	MagicAuth      SessionAuthenticationMethod = "MagicAuth"
	MicrosoftOauth SessionAuthenticationMethod = "MicrosoftOauth"
	Password       SessionAuthenticationMethod = "Password"
)

type UnauthorizedOrganization

type UnauthorizedOrganization struct {
	Organization Organization                     `json:"organization"`
	Reasons      []UnauthorizedOrganizationReason `json:"reasons"`
}

type UnauthorizedOrganizationReason

type UnauthorizedOrganizationReason struct {
	Type                         string                        `json:"type"`
	AllowedAuthenticationMethods []SessionAuthenticationMethod `json:"allowed_authentication_methods"`
}

type User

type User struct {

	// The User's unique identifier.
	ID string `json:"id"`

	// The User's first name.
	FirstName string `json:"first_name"`

	// The User's last name.
	LastName string `json:"last_name"`

	// The User's email.
	Email string `json:"email"`

	// The timestamp of when the User was created.
	CreatedAt string `json:"created_at"`

	// The timestamp of when the User was updated.
	UpdatedAt string `json:"updated_at"`

	// The type of the User: `managed` or `unmanaged`
	UserType UserType `json:"user_type"`

	// The ID of the SSO Profile. Only managed users have SSO Profiles.
	SSOProfileID string `json:"sso_profile_id"`

	// The timestamp when the user's email was verified.
	// Email verification is only applicable to unmanaged users.
	EmailVerifiedAt string `json:"email_verified_at"`

	// The ID of the Google OAuth Profile.
	// Only unmanaged users who sign in with Google OAuth have Google OAuth Profiles.
	GoogleOAuthProfileID string `json:"google_oauth_profile_id"`
}

User contains data about a particular User.

func AddUserToOrganization

func AddUserToOrganization(
	ctx context.Context,
	opts AddUserToOrganizationOpts,
) (User, error)

AddUserToOrganization adds an unmanaged User as a member of the given Organization.

func CompleteEmailVerification

func CompleteEmailVerification(
	ctx context.Context,
	opts CompleteEmailVerificationOpts,
) (User, error)

CompleteEmailVerification verifies user email using verification token that was sent to the user.

func CompletePasswordReset

func CompletePasswordReset(
	ctx context.Context,
	opts CompletePasswordResetOpts,
) (User, error)

CompletePasswordReset resets user password using token that was sent to the user.

func CreateUser

func CreateUser(
	ctx context.Context,
	opts CreateUserOpts,
) (User, error)

CreateUser creates a User.

func GetUser

func GetUser(
	ctx context.Context,
	opts GetUserOpts,
) (User, error)

GetUser gets a User.

func RemoveUserFromOrganization

func RemoveUserFromOrganization(
	ctx context.Context,
	opts RemoveUserFromOrganizationOpts,
) (User, error)

RemoveUserFromOrganization removes an unmanaged User as a member of the given Organization.

type UserType

type UserType string

UserType represents the type of the User

const (
	Unmanaged UserType = "unmanaged"
	Managed   UserType = "managed"
)

Constants that enumerate the UserType

type VerifySessionOpts

type VerifySessionOpts struct {
	Token    string `json:"token"`
	ClientID string `json:"client_id"`
}

type VerifySessionResponse

type VerifySessionResponse struct {
	Session Session `json:"session"`
	User    User    `json:"user"`
}

func VerifySession

func VerifySession(
	ctx context.Context,
	opts VerifySessionOpts,
) (VerifySessionResponse, error)

VerifySession verifies the session token returned by the authentication request.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL