auth reference

This reference follows the current server implementation. Use the SDK for customer flows; it manages identity proof and retries. Authentication and errors apply to every endpoint. Types below describe JSON: dates are ISO strings, ? means optional, and null differs from an omitted field. Responses may include additional fields. Schemas also enforce constraints that TypeScript cannot express; download the request JSON Schemas. Named response types are defined in the data model reference.

GET /v1/auth/oauth-config

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

OAuthConfig

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: getOAuthConfig.

GET /v1/auth/authorize

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ error: string;
  message: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: authorize.

POST /v1/auth/oauth/generate-state

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

No JSON body is required.

Response

JSON response shape

{ state: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: generateOAuthState.

POST /v1/auth/google

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ id_token: string;
  customerId?: string | undefined;
  state?: string | undefined;
  oauthState?: string | undefined;
  allowSignUp?: boolean | undefined;
  }

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

AuthResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: googleAuth.

POST /v1/auth/apple

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ id_token: string;
  authorization_code?: string | undefined;
  nonce?: string | undefined;
  user?: { name?: { firstName?: string | undefined;
  lastName?: string | undefined;
  } | undefined;
  email?: string | undefined;
  } | undefined;
  customerId?: string | undefined;
  state?: string | undefined;
  oauthState?: string | undefined;
  allowSignUp?: boolean | undefined;
  }

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

AuthResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: appleAuth.

POST /v1/auth/signup

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ email: string;
  password: string;
  name?: string | undefined;
  firstName?: string | undefined;
  lastName?: string | undefined;
  customerId?: string | undefined;
  state?: string | undefined;
  }

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Validation schemas: registerRequestSchema in the downloadable schema registry.

Response

JSON response shape

AuthResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: signup.

POST /v1/auth/signin

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ email: string;
  password: string;
  customerId?: string | undefined;
  state?: string | undefined;
  }

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Validation schemas: signInRequestSchema in the downloadable schema registry.

Response

JSON response shape

AuthResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: signin.

POST /v1/auth/maxvault/legacy-signin

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

This route supports an existing legacy migration only. New integrations must use the standard authentication routes.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ email: string;
  password: string;
  customerId?: string | undefined;
  state?: string | undefined;
  }

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Validation schemas: signInRequestSchema in the downloadable schema registry.

Response

JSON response shape

AuthResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: maxVaultLegacySignin.

POST /v1/auth/signout

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

{ operationId: string;
  state: "cancelled" | "exhausted" | "pending" | "started" | "retrying" | "confirmed" | "no_matching_purchase" | "interrupted";
  attempt: number;
  observedAt: string;
  parentOperationId?: string | null | undefined;
  }

{ version: 1;
  observedAt: string;
  policy: "account" | "app_store";
  verification: "unavailable" | "authoritative" | "verified_entitlements" | "cached";
  benefits: { identifier: string;
  source: "manual" | "apple" | "account" | "support_purchaser" | "preserved_import";
  effectiveUntil?: number | null | undefined;
  verifiedAt?: string | null | undefined;
  }[];
  truncated: boolean;
  providerEnvironment?: "Production" | "Sandbox" | "Xcode" | null | undefined;
  operationId?: string | null | undefined;
  attemptId?: string | null | undefined;
  requestId?: string | null | undefined;
  accessContextExpiresAt?: number | null | undefined;
  appleEvidence?: { observedAt: string;
  acquisition: "unavailable" | "rejected" | "app_transaction" | "receipt";
  purchaserComparison: "unavailable" | "first_observation" | "same" | "changed";
  collectionComplete: boolean;
  priorTransactionCount: number;
  submittedTransactionCount: number;
  retainedTransactionCount: number;
  missingProductIdentifiers: string[];
  previousPurchaserHash?: string | null | undefined;
  currentPurchaserHash?: string | null | undefined;
  acquisitionFailureStage?: string | null | undefined;
  } | null | undefined;
  }

{ occurrenceId: string;
  phase: "startup" | "runtime";
  operation: string;
  domain: string;
  code: string;
  message: string;
  underlyingErrors: { domain: string;
  code: string;
  message: string;
  }[];
  appVersion: string;
  buildNumber: string;
  truncated: boolean;
  stage?: string | undefined;
  migrationIdentifier?: string | undefined;
  relatedCrashReportId?: string | undefined;
  }

Response

JSON response shape

{ success: true;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: signOut.

POST /v1/auth/forgot-password

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ email: string;
  redirectUrl?: string | undefined;
  }

Validation schemas: forgotPasswordRequestSchema in the downloadable schema registry.

Response

JSON response shape

{ token?: string | undefined;
  success: true;
  message: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: forgotPassword.

POST /v1/auth/reset-password

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ token: string;
  password: string;
  }

Validation schemas: resetPasswordRequestSchema in the downloadable schema registry.

Response

JSON response shape

{ success: true;
  message: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: resetPassword.

POST /v1/auth/magic-link/request

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ email: string;
  redirectUrl: string;
  customerId?: string | undefined;
  }

Validation schemas: requestMagicLinkSchema in the downloadable schema registry.

Response

JSON response shape

MagicLinkRequestResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: requestMagicLink.

POST /v1/auth/magic-link/exchange

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ token: string;
  customerId?: string | undefined;
  }

Validation schemas: exchangeMagicLinkSchema in the downloadable schema registry.

Response

JSON response shape

AuthResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: exchangeMagicLink.

POST /v1/auth/reauthenticate

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ method: "password";
  password: string;
  } | { method: "apple";
  idToken: string;
  authorizationCode: string;
  nonce: string;
  } | { method: "google";
  idToken: string;
  } | { method: "magic_link";
  token: string;
  }

Validation schemas: reauthenticateRequestSchema in the downloadable schema registry.

Response

JSON response shape

{ session: AuthSession;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: reauthenticate.

POST /v1/auth/email-change/request

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ newEmail: string;
  }

Validation schemas: requestEmailChangeSchema in the downloadable schema registry.

Response

JSON response shape

{ success: true;
  expiresAt: number;
  emailUnreachable: boolean;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: requestEmailChange.

POST /v1/auth/email-change/password

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ newEmail: string;
  currentPassword: string;
  }

Response

JSON response shape

AuthResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: changeEmailWithPassword.

POST /v1/auth/email-change/confirm

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ token: string;
  }

Validation schemas: confirmEmailChangeSchema in the downloadable schema registry.

Response

JSON response shape

AuthResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: confirmEmailChange.

POST /v1/auth/password-change/complete

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ challengeToken: string;
  newPassword: string;
  }

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Validation schemas: completePasswordChangeSchema in the downloadable schema registry.

Response

JSON response shape

AuthResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: completePasswordChange.

POST /v1/auth/refresh

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ refreshToken: string;
  }

Validation schemas: refreshTokenRequestSchema in the downloadable schema registry.

Response

JSON response shape

{ session: { token: string;
  refreshToken: string;
  expiresAt: number;
  refreshExpiresAt: number | null;
  familyId: string;
  generation: number;
  authenticatedAt: number;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: refreshSession.

GET /v1/auth/user

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ user: { id: string;
  email: string;
  firstName: string | null;
  lastName: string | null;
  name: string;
  emailVerified: boolean;
  emailUnreachable: boolean;
  image: string | null;
  connectedAccounts: never[];
  preferences: UserPreferences;
  };
  customer: { customerId: string;
  isAnonymous: false;
  };
  }

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ user: CustomerAuthUser;
  customer: { customerId: string;
  isAnonymous: false;
  };
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: getCurrentUser.

PATCH /v1/auth/user

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ firstName?: string | undefined;
  lastName?: string | undefined;
  name?: string | undefined;
  imageUrl?: string | null | undefined;
  image?: string | null | undefined;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ user: { id: string;
  email: string;
  firstName: string | null;
  lastName: string | null;
  name: string;
  emailVerified: boolean;
  emailUnreachable: boolean;
  image: string | null;
  connectedAccounts: never[];
  preferences: UserPreferences;
  };
  }

JSON response shape

{ user: CustomerAuthUser;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: updateUser.

GET /v1/auth/accounts

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ accounts: ConnectedAccount[];
  }

JSON response shape

{ error: string;
  message: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: getAccounts.

DELETE /v1/auth/accounts/:id

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: id (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.id. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ success: true;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: deleteAccount.

POST /v1/auth/password

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ newPassword: string;
  oldPassword?: string | undefined;
  }

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ success: true;
  }

JSON response shape

{ session?: { token: string;
  refreshToken: string;
  expiresAt: number;
  refreshExpiresAt: number | null;
  familyId: string;
  generation: number;
  authenticatedAt: number;
  } | undefined;
  success: true;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: updatePassword.

GET /v1/auth/has-password

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ hasPassword: boolean;
  }

JSON response shape

{ error: string;
  message: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: hasPassword.

GET /v1/auth/preferences

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ preferences: UserPreferences;
  }

JSON response shape

{ error: string;
  message: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: getPreferences.

PATCH /v1/auth/preferences

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ [x: string]: unknown;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ preferences: UserPreferences;
  }

JSON response shape

{ preferences: Record<string, unknown>;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: updatePreferences.

POST /v1/auth/alias-customer

Authentication: Secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ fromCustomerId: string;
  toCustomerId: string;
  }

Validation schemas: aliasCustomerSchema in the downloadable schema registry.

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ success: true;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: aliasCustomer.

GET /v1/auth/account/preflight

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ canDelete: false;
  checks: { message: string;
  code: string;
  type: string;
  }[];
  }

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ canDelete: boolean;
  checks: AccountPreflightCheck[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: deleteUserAccountPreflight.

DELETE /v1/auth/account

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ password?: string | undefined;
  }

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ success: true;
  mode: string;
  customerPreserved: boolean;
  customerId: string | null;
  workspaceCustomerDetached: boolean;
  credentialAccountsDeleted: number;
  sharedIdentityPreserved: boolean;
  authIdentityDeleted: boolean;
  manualProviderRevocationRequired: never[];
  }

JSON response shape

{ success: true;
  scope: string;
  deletedAppIds: string[];
  authIdentityDeleted: boolean;
  manualProviderRevocationRequired: string[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: deleteUserAccount.

DELETE /v1/auth/user

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ password?: string | undefined;
  }

{ key: string;
  revision: number;
  occurrenceId: string;
  properties: Record<string, string>;
  attemptId?: string | undefined;
  sequence?: number | undefined;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ success: true;
  mode: string;
  customerPreserved: boolean;
  customerId: string | null;
  workspaceCustomerDetached: boolean;
  credentialAccountsDeleted: number;
  sharedIdentityPreserved: boolean;
  authIdentityDeleted: boolean;
  manualProviderRevocationRequired: never[];
  }

JSON response shape

{ success: true;
  scope: string;
  deletedAppIds: string[];
  authIdentityDeleted: boolean;
  manualProviderRevocationRequired: string[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: deleteUserAccount.

GET /v1/auth/callback/google

Authentication: Provider OAuth callback. Use the SDK-generated authorization flow and validated state; do not call this as a standalone app endpoint.

Request

Required query parameters: code and state from the provider authorization flow.

Response

A redirect completes the provider flow. Errors use the common error envelope.

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: inline route handler.

ALL /v1/auth/callback/apple

Authentication: Provider OAuth callback. Use the SDK-generated authorization flow and validated state; do not call this as a standalone app endpoint.

Request

Apple sends application/x-www-form-urlencoded form fields: required state, plus id_token, code, and user when supplied by Apple. This is the provider form-post callback, not a JSON app request.

Response

A redirect completes the provider flow. Errors use the common error envelope.

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: inline route handler.