@meistrari/auth-core 1.15.0 → 1.17.0

package/dist/index.d.ts

@@ -77,6 +77,11 @@ declare const Roles: {
  * Type representing a valid organization role.
  */
 type Role = typeof Roles[keyof typeof Roles];
+/**
+ * Role-based access control definitions mapping each role to its permissions.
+ *
+ * Used internally by the organization plugin to enforce access control.
+ */
 declare const rolesAccessControl: {
     "org:admin": {
         authorize<K_1 extends "member" | "access" | "organization" | "invitation" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins.Subset<"member" | "access" | "organization" | "invitation" | "team", {
@@ -163,6 +168,11 @@ declare const rolesAccessControl: {
         }>;
     };
 };
+/**
+ * Additional database fields added to the `user` table.
+ *
+ * @internal
+ */
 declare const userAdditionalFields: {
     lastActiveAt: {
         type: "date";
@@ -170,6 +180,11 @@ declare const userAdditionalFields: {
         defaultValue: null;
     };
 };
+/**
+ * Additional database fields added to the `organization` table.
+ *
+ * @internal
+ */
 declare const organizationAdditionalFields: {
     settings: {
         type: "json";
@@ -177,6 +192,11 @@ declare const organizationAdditionalFields: {
         required: false;
     };
 };
+/**
+ * Additional database fields added to the `member` table.
+ *
+ * @internal
+ */
 declare const memberAdditionalFields: {
     deletedAt: {
         type: "date";
@@ -189,6 +209,21 @@ declare const memberAdditionalFields: {
         defaultValue: null;
     };
 };
+/**
+ * Additional database fields added to the `invitation` table.
+ *
+ * @internal
+ */
+declare const invitationAdditionalFields: {
+    applicationId: {
+        type: "string";
+        input: true;
+        required: false;
+    };
+};
+/**
+ * Zod schema and type for the `user` claim within a JWT payload.
+ */
 declare const JWTPayloadUser: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -196,11 +231,20 @@ declare const JWTPayloadUser: z.ZodObject<{
     role: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 type JWTPayloadUser = z.infer<typeof JWTPayloadUser>;
+/**
+ * Zod schema and type for the `workspace` claim within a JWT payload.
+ */
 declare const JWTPayloadWorkspace: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
 }, z.core.$strip>;
 type JWTPayloadWorkspace = z.infer<typeof JWTPayloadWorkspace>;
+/**
+ * Zod schema and type for the full JWT payload issued by the auth API.
+ *
+ * Includes `email`, `user`, `workspace`, and `sessionKey` claims
+ * on top of the standard Better Auth JWT fields (`sub`, `iss`, `exp`, etc.).
+ */
 declare const JWTPayload: z.ZodObject<{
     email: z.ZodString;
     user: z.ZodObject<{
@@ -217,29 +261,58 @@ declare const JWTPayload: z.ZodObject<{
 }, z.core.$strip>;
 type JWTPayload = JWTPayload$1 & z.infer<typeof JWTPayload>;
 
+/**
+ * Metadata attached to an API key, identifying the owning user and workspace.
+ */
 type ApiKeyMetadata = {
+    /** The user who owns this API key. */
     user: {
         id: string;
         email: string;
     };
+    /** The workspace this API key belongs to. */
     workspace: {
         id: string;
         title: string;
     };
 } & Record<string, unknown>;
+/**
+ * A full API key including the secret key value.
+ *
+ * The secret `key` field is only returned once at creation time.
+ */
 type ApiKey = Omit<ApiKey$1, 'metadata' | 'name'> & {
+    /** Display name of the API key. */
     name: string;
+    /** Metadata identifying the key's owner and workspace. */
     metadata: ApiKeyMetadata;
 };
+/**
+ * An API key with the secret key value omitted.
+ *
+ * Used in list and get operations where the secret should not be exposed.
+ */
 type ApiKeyWithoutSecret = Omit<ApiKey, 'key'>;
+/**
+ * Payload for creating a new API key.
+ */
 type CreateApiKeyPayload = {
+    /** Display name for the API key. */
     name: string;
+    /** Time in milliseconds until the key expires. Omit for a non-expiring key. */
     expiresIn?: number;
+    /** Optional prefix prepended to the generated key for identification. */
     prefix?: string;
+    /** Optional metadata to attach to the key. */
     metadata?: ApiKeyMetadata;
 };
+/**
+ * Payload for updating an existing API key.
+ */
 type UpdateApiKeyPayload = {
+    /** The ID of the API key to update. */
     id: string;
+    /** The new display name for the API key. */
     name: string;
 };
 
@@ -260,6 +333,15 @@ type UpdateApiKeyPayload = {
 type Strict<T> = {
     [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
 };
+/**
+ * Creates a configured Better Auth API client with all required plugins.
+ *
+ * @param apiUrl - The base URL of the authentication API
+ * @param fetchOptions - Custom fetch options to include in all API requests
+ * @returns A fully-configured Better Auth client instance
+ *
+ * @internal
+ */
 declare function createAPIClient(apiUrl: string, fetchOptions?: BetterFetchOption): {
     useActiveOrganization: better_auth_client.AuthQueryAtom<better_auth.Prettify<{
         id: string;
@@ -3313,6 +3395,17 @@ declare function createAPIClient(apiUrl: string, fetchOptions?: BetterFetchOptio
                 statusText: string;
             };
         }>;
+        inviteUserToApplication: (options: InviteUserToApplicationOptions) => Promise<{
+            data: null;
+            error: {
+                message?: string | undefined;
+                status: number;
+                statusText: string;
+            };
+        } | {
+            data: CreateApplicationInvitationResponse;
+            error: null;
+        }>;
         startAuthorizationFlow: (applicationId: string, redirectUri: string, codeChallenge: string, organizationId: string) => Promise<{
             data: null;
             error: {
@@ -3401,7 +3494,7 @@ declare function createAPIClient(apiUrl: string, fetchOptions?: BetterFetchOptio
             data: CompleteAuthorizationFlowResponse;
             error: null;
         }>;
-        whoAmI: (accessToken: string) => Promise<{
+        whoAmI: (accessToken: string, options?: WhoAmIOptions) => Promise<{
             data: null;
             error: {
                 message?: string | undefined;
@@ -4365,112 +4458,305 @@ declare function createAPIClient(apiUrl: string, fetchOptions?: BetterFetchOptio
         };
     };
 };
+/**
+ * The configured Better Auth client type with all plugins applied.
+ *
+ * @internal
+ */
 type APIClient = ReturnType<typeof createAPIClient>;
+/** An authenticated user. */
 type User = APIClient['$Infer']['Session']['user'];
+/** A user session containing the user and session metadata. */
 type Session = APIClient['$Infer']['Session'];
-type Organization = Strict<APIClient['$Infer']['Organization']>;
+/** An organization the user belongs to. */
+type BaseOrganization = Strict<APIClient['$Infer']['Organization']>;
+/** A team within an organization. */
 type Team = Strict<APIClient['$Infer']['Team']>;
+/** A pending invitation to join an organization. */
 type Invitation = Strict<APIClient['$Infer']['Invitation']>;
+/** A member of an organization with role information. */
 type Member = Strict<APIClient['$Infer']['Member']>;
+/**
+ * Custom settings that can be applied to an organization.
+ */
 type OrganizationSettings = {
+    /** Whether file storage is disabled for this organization. */
     disableStorage?: boolean;
+    /** Number of hours to retain data before automatic cleanup. */
     dataRetentionHours?: number;
 };
-type ExtendedOrganization = Organization & {
+/**
+ * An organization with optional custom settings.
+ */
+type ExtendedOrganization = BaseOrganization & {
     settings?: OrganizationSettings;
 };
+/**
+ * A complete organization object including its members, invitations, and teams.
+ */
 type FullOrganization = Omit<ExtendedOrganization, 'slug'> & {
     slug: string | null;
     members: Member[];
     invitations: Invitation[];
     teams: Team[];
 };
+/**
+ * An organization as returned by the "who am I" endpoint, where related
+ * collections (`members`, `teams`, `invitations`) are optional and only
+ * populated when explicitly requested via the `include` query parameter.
+ */
+type WhoAmIOrganization = Omit<FullOrganization, 'members' | 'invitations' | 'teams'> & {
+    members?: Member[];
+    invitations?: Invitation[];
+    teams?: Team[];
+};
+/**
+ * A record linking a user to a team.
+ */
 type TeamMember = {
+    /** Unique identifier for this team membership. */
     id: string;
+    /** The team this membership belongs to. */
     teamId: string;
+    /** The user who is a member of the team. */
     userId: string;
+    /** When the user was added to the team. */
     createdAt: Date;
 };
 
+/**
+ * Keys of the organization's related collections that can be optionally
+ * included in the "who am I" response.
+ */
+type WhoAmIInclude = 'members' | 'teams' | 'invitations';
+/**
+ * Represents a registered OAuth application.
+ */
 type Application = {
+    /** Unique application identifier. */
     id: string;
+    /** Display name of the application. */
     name: string;
+    /** Human-readable description of the application. */
     description: string;
+    /** Allowed OAuth redirect URIs for this application. */
     redirectUris: string[];
 };
+/**
+ * Response returned when listing candidate organizations for an application.
+ */
 type ListCandidateOrganizationsResponse = {
+    /** The application being queried. */
     application: Application;
+    /** Organizations where the user is a member and the application is entitled. */
     organizations: FullOrganization[];
 };
+/**
+ * Response returned when starting an authorization flow.
+ */
 type StartAuthorizationFlowResponse = {
+    /** The authorization code to exchange for tokens. */
     code: string;
 };
+/**
+ * Response returned when completing an authorization flow or refreshing tokens.
+ */
 type CompleteAuthorizationFlowResponse = {
+    /** Short-lived JWT access token. */
     accessToken: string;
+    /** Long-lived refresh token for obtaining new access tokens. */
     refreshToken: string;
+    /** The authenticated user. */
     user: User;
+    /** The organization the tokens are scoped to. */
     organization: FullOrganization;
 };
+/**
+ * Response returned by the "who am I" endpoint.
+ *
+ * By default, the `organization` only contains the base organization fields.
+ * The `members`, `teams`, and `invitations` collections are only populated
+ * when explicitly requested via the `include` query parameter.
+ */
 type WhoAmIResponse = {
+    /** The authenticated user. */
     user: User;
-    organization: FullOrganization;
+    /** The user's active organization. */
+    organization: WhoAmIOrganization;
 };
+/**
+ * Options accepted by the "who am I" client method.
+ */
+type WhoAmIOptions = {
+    /**
+     * Collections to include in the returned organization. When omitted or
+     * empty, only the base organization fields are returned.
+     */
+    include?: WhoAmIInclude[];
+};
+type InviteUserToApplicationOptions = {
+    organizationId: string;
+    applicationId: string;
+    email: string;
+    role: Role;
+    teamId?: string;
+    resend?: boolean;
+    sendEmail?: boolean;
+};
+type ApplicationInvitationResponse = {
+    id: string;
+    organizationId: string;
+    email: string;
+    role: string | null;
+    teamId: string | null;
+    applicationId: string | null;
+    status: string;
+    expiresAt: Date | string;
+    inviterId: string;
+    createdAt: Date | string;
+};
+type CreateApplicationInvitationResponse = {
+    data?: ApplicationInvitationResponse;
+};
+/**
+ * Response returned when starting a device authorization flow (RFC 8628).
+ */
 type DeviceAuthorizationResponse = {
+    /** The device verification code for polling. */
     device_code: string;
+    /** The user-facing code to enter on the verification page. */
     user_code: string;
+    /** The URI the user should visit to authorize the device. */
     verification_uri: string;
+    /** A complete URI including the user code for convenience. */
     verification_uri_complete: string;
+    /** Number of seconds until the device code expires. */
     expires_in: number;
+    /** Minimum polling interval in seconds. */
     interval: number;
 };
+/**
+ * Minimal application info shown in device authorization context.
+ *
+ * @internal
+ */
 type DeviceContextApplication = {
+    /** Unique application identifier. */
     id: string;
+    /** Display name of the application. */
     name: string;
+    /** Human-readable description, or `null` if not set. */
     description: string | null;
 };
+/**
+ * Context information for a pending device authorization request.
+ */
 type DeviceAuthorizationContextResponse = {
+    /** The application that initiated the device flow, with verification status. */
     requester: DeviceContextApplication & {
         isVerified: boolean;
     };
+    /** The target application the requester wants access to. */
     target: DeviceContextApplication;
+    /** Organizations the user can authorize the device for. */
     organizations: FullOrganization[];
+    /** Organization pre-selected by the requester, if any. */
     preselectedOrganizationId: string | null;
+    /** Current status of the device authorization request. */
     status: 'pending' | 'approved' | 'denied';
+    /** Seconds remaining before the device code expires. */
     expiresIn: number;
 };
+/**
+ * Response returned when approving or denying a device authorization request.
+ */
 type DeviceAuthorizationActionResponse = {
+    /** Whether the action was performed successfully. */
     success: boolean;
 };
 
+/**
+ * Base error class for all SDK errors.
+ *
+ * Extends the native `Error` with a machine-readable `code` property
+ * that can be used for programmatic error handling.
+ */
 declare class BaseError extends Error {
+    /** Machine-readable error code (e.g. `"INVALID_SOCIAL_PROVIDER"`). */
     code: string;
+    /**
+     * @param code - A machine-readable error code
+     * @param message - A human-readable error message
+     * @param options - Standard `ErrorOptions` (e.g. `cause`)
+     */
     constructor(code: string, message: string, options?: ErrorOptions);
 }
 
+/**
+ * Generic error thrown by the `ApplicationService`.
+ *
+ * All application-specific errors extend this class, so you can catch
+ * `ApplicationError` to handle any application-related failure.
+ */
 declare class ApplicationError extends BaseError {
     constructor(message: string, options?: ErrorOptions);
 }
+/**
+ * Thrown when a refresh token has expired or been revoked.
+ *
+ * The client should discard its stored tokens and prompt the user
+ * to re-authenticate.
+ */
 declare class RefreshTokenExpiredError extends ApplicationError {
     constructor(options?: ErrorOptions);
 }
+/**
+ * Thrown when an authorization flow fails unexpectedly.
+ */
 declare class AuthorizationFlowError extends ApplicationError {
     constructor(message: string, options?: ErrorOptions);
 }
+/**
+ * Thrown when an operation requires an authenticated user but no session exists.
+ */
 declare class UserNotLoggedInError extends ApplicationError {
     constructor(message: string, options?: ErrorOptions);
 }
+/**
+ * Thrown during device code polling when the user has not yet authorized the request.
+ *
+ * The client should continue polling at the specified interval.
+ */
 declare class DeviceAuthorizationPendingError extends ApplicationError {
     constructor(options?: ErrorOptions);
 }
+/**
+ * Thrown when the client is polling too frequently during the device flow.
+ *
+ * The client should increase its polling interval before retrying.
+ */
 declare class DeviceAuthorizationSlowDownError extends ApplicationError {
     constructor(options?: ErrorOptions);
 }
+/**
+ * Thrown when the user explicitly denies the device authorization request.
+ */
 declare class DeviceAccessDeniedError extends ApplicationError {
     constructor(options?: ErrorOptions);
 }
+/**
+ * Thrown when the device code has expired or has already been consumed.
+ *
+ * The client must start a new device authorization flow.
+ */
 declare class DeviceCodeExpiredError extends ApplicationError {
     constructor(options?: ErrorOptions);
 }
+/**
+ * Thrown when the authorization server returns a transient error during the device flow.
+ *
+ * The token exchange can be safely retried.
+ */
 declare class DeviceTransientServerError extends ApplicationError {
     constructor(options?: ErrorOptions);
 }
@@ -4479,7 +4765,10 @@ declare class DeviceTransientServerError extends ApplicationError {
  * Service for managing applications and their candidate organizations.
  *
  * Provides functionality for:
- * - Listing candidate organizations for an application
+ * - OAuth authorization code flow (PKCE)
+ * - Device authorization flow (RFC 8628)
+ * - Token management (refresh, exchange)
+ * - Organization switching
  */
 declare class ApplicationService {
     private client;
@@ -4505,6 +4794,13 @@ declare class ApplicationService {
         organizations: FullOrganization[];
         application?: Application | undefined;
     }>;
+    /**
+     * Invites a user to an application through an organization entitlement.
+     *
+     * @param options - Invitation details including organization, application, email, and role
+     * @returns The created invitation
+     */
+    inviteUserToApplication(options: InviteUserToApplicationOptions): Promise<CreateApplicationInvitationResponse>;
     /**
      * Starts an authorization flow for a specific application.
      *
@@ -4514,10 +4810,57 @@ declare class ApplicationService {
      * @param organizationId - The organization ID to start the authorization flow for
      */
     startAuthorizationFlow(applicationId: string, redirectUri: string, codeChallenge: string, organizationId: string): Promise<StartAuthorizationFlowResponse>;
+    /**
+     * Starts a device authorization flow (RFC 8628).
+     *
+     * Returns a device code and user code that the end user must enter
+     * on the verification URI to authorize the device.
+     *
+     * @param requesterApplicationId - The application requesting authorization
+     * @param targetApplicationId - The target application to gain access to
+     * @returns Device authorization details including codes and verification URI
+     */
     startDeviceAuthorizationFlow(requesterApplicationId: string, targetApplicationId: string): Promise<DeviceAuthorizationResponse>;
+    /**
+     * Retrieves the context for a pending device authorization request.
+     *
+     * Used by the authorization page to display details about the requesting
+     * and target applications before the user approves or denies.
+     *
+     * @param userCode - The user code from the device authorization response
+     * @returns Context including application info, available organizations, and status
+     */
     getDeviceAuthorizationContext(userCode: string): Promise<DeviceAuthorizationContextResponse>;
+    /**
+     * Approves a pending device authorization request.
+     *
+     * @param userCode - The user code identifying the device authorization request
+     * @param organizationId - The organization to authorize the device for
+     * @returns Confirmation of the approval action
+     */
     approveDeviceAuthorizationFlow(userCode: string, organizationId: string): Promise<DeviceAuthorizationActionResponse>;
+    /**
+     * Denies a pending device authorization request.
+     *
+     * @param userCode - The user code identifying the device authorization request
+     * @returns Confirmation of the denial action
+     */
     denyDeviceAuthorizationFlow(userCode: string): Promise<DeviceAuthorizationActionResponse>;
+    /**
+     * Exchanges a device code for access and refresh tokens.
+     *
+     * This should be called by the device client while polling. It will throw
+     * typed errors to indicate the polling state (pending, slow down, denied, expired).
+     *
+     * @param deviceCode - The device code obtained from {@link startDeviceAuthorizationFlow}
+     * @returns Access and refresh tokens along with user and organization info
+     *
+     * @throws {DeviceAuthorizationPendingError} The user hasn't authorized yet — keep polling
+     * @throws {DeviceAuthorizationSlowDownError} Polling too fast — increase the interval
+     * @throws {DeviceAccessDeniedError} The user denied the request
+     * @throws {DeviceCodeExpiredError} The device code has expired
+     * @throws {DeviceTransientServerError} Transient server error — safe to retry
+     */
     exchangeDeviceCodeForTokens(deviceCode: string): Promise<CompleteAuthorizationFlowResponse>;
     /**
      * Completes an authorization flow for a specific application.
@@ -4537,10 +4880,15 @@ declare class ApplicationService {
     /**
      * Gets the current user and organization for a specific application.
      *
+     * By default, the returned organization does not include its `members`,
+     * `teams`, or `invitations` collections. Pass `options.include` to request
+     * any of them explicitly.
+     *
      * @param accessToken - The access token to use for the who am I request
+     * @param options - Optional include list controlling which relations are loaded
      * @returns The current user and organization
      */
-    whoAmI(accessToken: string): Promise<WhoAmIResponse>;
+    whoAmI(accessToken: string, options?: WhoAmIOptions): Promise<WhoAmIResponse>;
     /**
      * Switches the active organization for the authenticated user.
      *
@@ -4564,29 +4912,72 @@ declare class ApplicationService {
     logout(refreshToken: string): Promise<void>;
 }
 
+/**
+ * Fields that can be updated on an organization.
+ */
 type UpdateOrganizationPayload = Partial<Pick<ExtendedOrganization, 'name' | 'logo' | 'settings'>>;
+/**
+ * Pagination options for listing organization members.
+ */
 type ListMembersOptions = {
+    /** Maximum number of members to return. */
     limit?: number;
+    /** Number of members to skip for pagination. */
     offset?: number;
 };
+/**
+ * Options for inviting a user to the active organization.
+ */
 type InviteUserToOrganizationOptions = {
+    /** Email address of the user to invite. */
     userEmail: string;
+    /** Organization role to assign to the invited user. */
     role: Role;
+    /** Optional team to add the user to upon acceptance. */
     teamId?: string;
+    /** Whether to resend the invitation if one already exists for this email. */
     resend?: boolean;
+    /**
+     * Application scope for legacy callers that still pass this option through
+     * the organization invitation path.
+     *
+     * New app-scoped invitations should use
+     * `applications.inviteUserToApplication`, which calls
+     * `POST /api/auth/applications/invitations`. The server rejects legacy
+     * organization invitation creation when this field is present.
+     */
+    applicationId?: string;
 };
+/**
+ * Options for removing a user from the active organization.
+ *
+ * Provide either `memberId` or `userEmail`, but not both.
+ */
 type RemoveUserFromOrganizationOptions = {
+    /** The member ID to remove. */
     memberId: string;
     userEmail?: never;
 } | {
+    /** The user's email address to remove. */
     userEmail: string;
     memberId?: never;
 };
+/**
+ * Options for updating a member's role within the organization.
+ */
 type UpdateMemberRoleOptions = {
+    /** The member ID whose role should be updated. */
     memberId: string;
+    /** The new role to assign. */
     role: Role;
 };
+/**
+ * Payload for creating a new team.
+ */
 type CreateTeamPayload = Pick<Team, 'name'>;
+/**
+ * Payload for updating an existing team.
+ */
 type UpdateTeamPayload = Pick<Team, 'name'>;
 
 /**
@@ -4668,10 +5059,7 @@ declare class OrganizationService {
     /**
      * Updates an organization's details.
      *
-     * @param payload - The organization fields to update
-     * @param payload.name - New organization name
-     * @param payload.logo - New organization logo URL
-     * @param payload.settings - New organization settings
+     * @param payload - The organization fields to update (name, logo, settings)
      * @returns The updated organization
      */
     updateOrganization(payload: UpdateOrganizationPayload): Promise<ExtendedOrganization>;
@@ -4747,10 +5135,11 @@ declare class OrganizationService {
      * @param options.userEmail - Email address of the user to invite
      * @param options.role - Role to assign to the invited user
      * @param options.teamId - Team ID to add the user to
+     * @param options.applicationId - Legacy application scope; prefer applications.inviteUserToApplication for new app-scoped invites
      * @param options.resend - Whether to resend if invitation already exists
      * @returns The created invitation
      */
-    inviteUserToOrganization({ userEmail, role, teamId, resend }: InviteUserToOrganizationOptions): Promise<NonNullable<{
+    inviteUserToOrganization({ userEmail, role, teamId, resend, applicationId }: InviteUserToOrganizationOptions): Promise<NonNullable<{
         id: string;
         organizationId: string;
         email: string;
@@ -4781,14 +5170,16 @@ declare class OrganizationService {
      * Accepts an organization invitation.
      *
      * @param id - The invitation ID to accept
+     * @returns Object containing the application's `homeUrl` when the invitation is
+     *   scoped to an application that defines one; otherwise `null`.
      */
-    acceptInvitation(id: string): Promise<void>;
+    acceptInvitation(id: string): Promise<{
+        homeUrl: string | null;
+    }>;
     /**
      * Removes a user from the active organization.
      *
-     * @param options - User identifier (either memberId or userEmail must be provided)
-     * @param options.memberId - The member ID to remove
-     * @param options.userEmail - The user email to remove
+     * @param options - Provide either `memberId` or `userEmail` to identify the user
      */
     removeUserFromOrganization({ memberId, userEmail }: RemoveUserFromOrganizationOptions): Promise<void>;
     /**
@@ -4802,8 +5193,7 @@ declare class OrganizationService {
     /**
      * Creates a new team within the active organization.
      *
-     * @param payload - Team configuration
-     * @param payload.name - The name of the team
+     * @param payload - Team configuration with a `name` field
      * @returns The created team
      */
     createTeam(payload: CreateTeamPayload): Promise<{
@@ -4817,8 +5207,7 @@ declare class OrganizationService {
      * Updates an existing team's details.
      *
      * @param id - The team ID to update
-     * @param payload - Team fields to update
-     * @param payload.name - The new team name
+     * @param payload - Team fields to update (currently supports `name`)
      * @returns The updated team
      */
     updateTeam(id: string, payload: UpdateTeamPayload): Promise<{
@@ -4880,20 +5269,39 @@ declare class OrganizationService {
     removeTeamMember(teamId: string, userId: string): Promise<void>;
 }
 
+/**
+ * Options for signing in with a social provider (Google or Microsoft).
+ */
 type SocialSignInOptions = {
+    /** The social identity provider to authenticate with. */
     provider: 'google' | 'microsoft';
+    /** URL to redirect to after successful authentication. */
     callbackURL: string;
+    /** URL to redirect to if authentication fails. Falls back to the API's default error page if not provided. */
     errorCallbackURL?: string;
 };
+/**
+ * Options for signing in via SAML Single Sign-On.
+ */
 type SignInWithSamlOptions = {
+    /** The user's email address, used to resolve the correct SAML identity provider. */
     email: string;
+    /** URL to redirect to after successful authentication. */
     callbackURL: string;
+    /** URL to redirect to if authentication fails. Falls back to the API's default error page if not provided. */
     errorCallbackURL?: string;
 };
+/**
+ * Options for signing in with email and password credentials.
+ */
 type SignInWithEmailAndPasswordOptions = {
+    /** The user's email address. */
     email: string;
+    /** The user's password. */
     password: string;
+    /** URL to redirect to after successful authentication. */
     callbackURL: string;
+    /** URL to redirect to if authentication fails. */
     errorCallbackURL?: string;
 };
 
@@ -5026,10 +5434,10 @@ declare class SessionService {
 }
 
 /**
- * Service for managing API keys
+ * Service for managing API keys.
  *
- * Provides comprehensive API key management including:
- * - API key CRUD operations
+ * Provides CRUD operations for API keys scoped to the authenticated
+ * user or their active organization.
  */
 declare class ApiKeyService {
     private client;
@@ -5039,16 +5447,52 @@ declare class ApiKeyService {
      * @param client - The API client for making API key requests
      */
     constructor(client: APIClient);
+    /**
+     * Creates a new API key.
+     *
+     * The returned object includes the secret `key` value, which is only
+     * available at creation time and cannot be retrieved later.
+     *
+     * @param payload - The API key configuration
+     * @returns The created API key including the secret key value
+     */
     createApiKey(payload: CreateApiKeyPayload): Promise<ApiKey>;
+    /**
+     * Retrieves an API key by its ID.
+     *
+     * @param id - The API key ID
+     * @returns The API key (without the secret key value)
+     */
     getApiKey(id: string): Promise<ApiKeyWithoutSecret>;
+    /**
+     * Lists all API keys owned by the authenticated user.
+     *
+     * @returns An object containing the API keys array and pagination metadata
+     */
     listApiKeys(): Promise<{
         apiKeys: ApiKeyWithoutSecret[];
         total: number;
         limit: number | undefined;
         offset: number | undefined;
     }>;
+    /**
+     * Lists all API keys belonging to the active organization.
+     *
+     * @returns An array of API keys (without secret key values)
+     */
     listOrganizationApiKeys(): Promise<ApiKeyWithoutSecret[]>;
+    /**
+     * Updates an existing API key.
+     *
+     * @param payload - The fields to update
+     * @returns The updated API key (without the secret key value)
+     */
     updateApiKey(payload: UpdateApiKeyPayload): Promise<ApiKeyWithoutSecret>;
+    /**
+     * Permanently deletes an API key.
+     *
+     * @param id - The API key ID to delete
+     */
     deleteApiKey(id: string): Promise<{
         success: boolean;
     }>;
@@ -5184,5 +5628,5 @@ declare function validateToken(token: string, apiUrl: string): Promise<boolean>;
  */
 declare function extractTokenPayload(token: string): JWTPayload;
 
-export { ApplicationError, AuthClient, AuthorizationFlowError, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadUser, JWTPayloadWorkspace, RefreshTokenExpiredError, Roles, UserNotLoggedInError, ac, createAPIClient, extractTokenPayload, isTokenExpired, memberAdditionalFields, organizationAdditionalFields, rolesAccessControl, userAdditionalFields, validateToken };
-export type { APIClient, ApiKey, ApiKeyMetadata, ApiKeyWithoutSecret, Application, CompleteAuthorizationFlowResponse, CreateApiKeyPayload, CreateTeamPayload, DeviceAuthorizationActionResponse, DeviceAuthorizationContextResponse, DeviceAuthorizationResponse, FullOrganization, Invitation, InviteUserToOrganizationOptions, ListCandidateOrganizationsResponse, ListMembersOptions, Member, ExtendedOrganization as Organization, RemoveUserFromOrganizationOptions, Role, Session, SignInWithEmailAndPasswordOptions, SignInWithSamlOptions, SocialSignInOptions, StartAuthorizationFlowResponse, Team, TeamMember, UpdateApiKeyPayload, UpdateMemberRoleOptions, UpdateOrganizationPayload, UpdateTeamPayload, User, WhoAmIResponse };
+export { ApplicationError, AuthClient, AuthorizationFlowError, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadUser, JWTPayloadWorkspace, RefreshTokenExpiredError, Roles, UserNotLoggedInError, ac, createAPIClient, extractTokenPayload, invitationAdditionalFields, isTokenExpired, memberAdditionalFields, organizationAdditionalFields, rolesAccessControl, userAdditionalFields, validateToken };
+export type { APIClient, ApiKey, ApiKeyMetadata, ApiKeyWithoutSecret, Application, ApplicationInvitationResponse, BaseOrganization, CompleteAuthorizationFlowResponse, CreateApiKeyPayload, CreateApplicationInvitationResponse, CreateTeamPayload, DeviceAuthorizationActionResponse, DeviceAuthorizationContextResponse, DeviceAuthorizationResponse, DeviceContextApplication, FullOrganization, Invitation, InviteUserToApplicationOptions, InviteUserToOrganizationOptions, ListCandidateOrganizationsResponse, ListMembersOptions, Member, ExtendedOrganization as Organization, OrganizationSettings, RemoveUserFromOrganizationOptions, Role, Session, SignInWithEmailAndPasswordOptions, SignInWithSamlOptions, SocialSignInOptions, StartAuthorizationFlowResponse, Strict, Team, TeamMember, UpdateApiKeyPayload, UpdateMemberRoleOptions, UpdateOrganizationPayload, UpdateTeamPayload, User, WhoAmIInclude, WhoAmIOptions, WhoAmIOrganization, WhoAmIResponse };