multi_factor_auth.go

// Code generated by oagen. DO NOT EDIT.

package workos

import (
	"context"
	"fmt"
	"net/url"
)

// MultiFactorAuthService handles MultiFactorAuth operations.
type MultiFactorAuthService struct {
	client *Client
}

// MultiFactorAuthVerifyChallengeParams contains the parameters for VerifyChallenge.
type MultiFactorAuthVerifyChallengeParams struct {
	// Code is the one-time code to verify.
	Code string `json:"code"`
}

// VerifyChallenge
// Verifies an Authentication Challenge.
func (s *MultiFactorAuthService) VerifyChallenge(ctx context.Context, id string, params *MultiFactorAuthVerifyChallengeParams, opts ...RequestOption) (*AuthenticationChallengeVerifyResponse, error) {
	var result AuthenticationChallengeVerifyResponse
	_, err := s.client.request(ctx, "POST", fmt.Sprintf("/auth/challenges/%s/verify", url.PathEscape(id)), nil, params, &result, opts)
	if err != nil {
		return nil, err
	}
	return &result, nil
}

// MultiFactorAuthEnrollFactorParams contains the parameters for EnrollFactor.
type MultiFactorAuthEnrollFactorParams struct {
	// Type is the type of factor to enroll.
	Type AuthenticationFactorsCreateRequestType `json:"type"`
	// PhoneNumber is required when type is 'sms'.
	PhoneNumber *string `json:"phone_number,omitempty"`
	// TOTPIssuer is required when type is 'totp'.
	TOTPIssuer *string `json:"totp_issuer,omitempty"`
	// TOTPUser is required when type is 'totp'.
	TOTPUser *string `json:"totp_user,omitempty"`
	// UserID is the ID of the user to associate the factor with.
	UserID *string `json:"user_id,omitempty"`
}

// EnrollFactor
// Enrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge.
func (s *MultiFactorAuthService) EnrollFactor(ctx context.Context, params *MultiFactorAuthEnrollFactorParams, opts ...RequestOption) (*AuthenticationFactorEnrolled, error) {
	var result AuthenticationFactorEnrolled
	_, err := s.client.request(ctx, "POST", "/auth/factors/enroll", nil, params, &result, opts)
	if err != nil {
		return nil, err
	}
	return &result, nil
}

// GetFactor
// Gets an Authentication Factor.
func (s *MultiFactorAuthService) GetFactor(ctx context.Context, id string, opts ...RequestOption) (*AuthenticationFactor, error) {
	var result AuthenticationFactor
	_, err := s.client.request(ctx, "GET", fmt.Sprintf("/auth/factors/%s", url.PathEscape(id)), nil, nil, &result, opts)
	if err != nil {
		return nil, err
	}
	return &result, nil
}

// DeleteFactor
// Permanently deletes an Authentication Factor. It cannot be undone.
func (s *MultiFactorAuthService) DeleteFactor(ctx context.Context, id string, opts ...RequestOption) error {
	_, err := s.client.request(ctx, "DELETE", fmt.Sprintf("/auth/factors/%s", url.PathEscape(id)), nil, nil, nil, opts)
	return err
}

// MultiFactorAuthChallengeFactorParams contains the parameters for ChallengeFactor.
type MultiFactorAuthChallengeFactorParams struct {
	// SmsTemplate is a custom template for the SMS message. Use the {{code}} placeholder to include the verification code.
	SmsTemplate *string `json:"sms_template,omitempty"`
}

// ChallengeFactor
// Creates a Challenge for an Authentication Factor.
func (s *MultiFactorAuthService) ChallengeFactor(ctx context.Context, id string, params *MultiFactorAuthChallengeFactorParams, opts ...RequestOption) (*AuthenticationChallenge, error) {
	var result AuthenticationChallenge
	_, err := s.client.request(ctx, "POST", fmt.Sprintf("/auth/factors/%s/challenge", url.PathEscape(id)), nil, params, &result, opts)
	if err != nil {
		return nil, err
	}
	return &result, nil
}

// MultiFactorAuthListUserAuthFactorsParams contains the parameters for ListUserAuthFactors.
type MultiFactorAuthListUserAuthFactorsParams struct {
	PaginationParams
}

// ListUserAuthFactors list authentication factors
// Lists the [authentication factors](https://workos.com/docs/reference/authkit/mfa/authentication-factor) for a user.
func (s *MultiFactorAuthService) ListUserAuthFactors(ctx context.Context, userlandUserID string, params *MultiFactorAuthListUserAuthFactorsParams, opts ...RequestOption) *Iterator[AuthenticationFactor] {
	return newIterator[AuthenticationFactor](ctx, s.client, "GET", fmt.Sprintf("/user_management/users/%s/auth_factors", url.PathEscape(userlandUserID)), params, "after", "data", opts, map[string]string{"limit": "10", "order": "desc"})
}

// MultiFactorAuthCreateUserAuthFactorParams contains the parameters for CreateUserAuthFactor.
type MultiFactorAuthCreateUserAuthFactorParams struct {
	// Type is the type of the factor to enroll.
	Type string `json:"type"`
	// TOTPIssuer is your application or company name displayed in the user's authenticator app.
	TOTPIssuer *string `json:"totp_issuer,omitempty"`
	// TOTPUser is the user's account name displayed in their authenticator app.
	TOTPUser *string `json:"totp_user,omitempty"`
	// TOTPSecret is the Base32-encoded shared secret for TOTP factors. This can be provided when creating the auth factor, otherwise it will be generated. The algorithm used to derive TOTP codes is SHA-1, the code length is 6 digits, and the timestep is 30 seconds – the secret must be compatible with these parameters.
	TOTPSecret *string `json:"totp_secret,omitempty"`
}

// CreateUserAuthFactor enroll an authentication factor
// Enrolls a user in a new [authentication factor](https://workos.com/docs/reference/authkit/mfa/authentication-factor).
func (s *MultiFactorAuthService) CreateUserAuthFactor(ctx context.Context, userlandUserID string, params *MultiFactorAuthCreateUserAuthFactorParams, opts ...RequestOption) (*UserAuthenticationFactorEnrollResponse, error) {
	var result UserAuthenticationFactorEnrollResponse
	_, err := s.client.request(ctx, "POST", fmt.Sprintf("/user_management/users/%s/auth_factors", url.PathEscape(userlandUserID)), nil, params, &result, opts)
	if err != nil {
		return nil, err
	}
	return &result, nil
}