@proveanything/smartlinks 2.1.12 → 2.1.13

package/dist/api/authKit.d.ts

@@ -1,4 +1,4 @@
-import type { AuthLoginResponse, AppleLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, AuthKitConfigInput, AuthKitSetIdentityResponse, AuthKitInviteRequest, AuthKitInviteResponse, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaTotpEnrollResponse, MfaEnrolledResponse, MfaFactor, MfaFactorsResponse, TrustedDevice } from "../types/authKit.js";
+import type { AuthLoginResponse, AppleLoginOptions, MicrosoftLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, AuthKitConfigInput, AuthKitSetIdentityResponse, AuthKitInviteRequest, AuthKitInviteResponse, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaTotpEnrollResponse, MfaEnrolledResponse, MfaFactor, MfaFactorsResponse, TrustedDevice } from "../types/authKit.js";
 /**
  * Namespace containing helper functions for the new AuthKit API.
  * Legacy collection-based authKit helpers retained (marked as *Legacy*).
@@ -93,6 +93,22 @@ export declare namespace authKit {
      * @see AppleLoginOptions
      */
     function appleLogin(clientId: string, identityToken: string, opts?: AppleLoginOptions): Promise<AuthLoginResponse>;
+    /**
+     * Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft
+     * accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer
+     * token is stored and the cache invalidated.
+     *
+     * Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`)
+     * against the app in the public config's `microsoftClientId`. A site on its own domain can't be a
+     * registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in
+     * page in a popup, which calls this with `opts.returnOrigin` and hands the result back.
+     *
+     * Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400),
+     * `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 —
+     * the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409),
+     * `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+     */
+    function microsoftLogin(clientId: string, idToken: string, opts?: MicrosoftLoginOptions): Promise<AuthLoginResponse>;
     /**
      * Exchange a refresh token for a fresh access token (public — the refresh token IS
      * the credential). **Native sessions only**; refresh tokens are issued only when the

package/dist/api/authKit.js

@@ -139,6 +139,30 @@ export var authKit;
         return res;
     }
     authKit.appleLogin = appleLogin;
+    /**
+     * Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft
+     * accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer
+     * token is stored and the cache invalidated.
+     *
+     * Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`)
+     * against the app in the public config's `microsoftClientId`. A site on its own domain can't be a
+     * registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in
+     * page in a popup, which calls this with `opts.returnOrigin` and hands the result back.
+     *
+     * Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400),
+     * `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 —
+     * the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409),
+     * `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+     */
+    async function microsoftLogin(clientId, idToken, opts) {
+        const res = await post(`/authkit/${encodeURIComponent(clientId)}/auth/microsoft`, Object.assign({ idToken }, opts));
+        if (res.token) {
+            setBearerToken(res.token);
+            invalidateCache();
+        }
+        return res;
+    }
+    authKit.microsoftLogin = microsoftLogin;
     /* ===================================
      * Native session refresh (public)
      * =================================== */

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.12  |  Generated: 2026-11-08T14:30:42.034Z
+Version: 2.1.13  |  Generated: 2026-11-09T11:51:55.948Z
 
 This is a concise summary of all available API functions and types.
 
@@ -4624,6 +4624,24 @@ interface LogoutResponse {
 }
 ```
 
+**MicrosoftLoginOptions** (interface)
+```typescript
+interface MicrosoftLoginOptions {
+  returnOrigin?: string
+  trustedDeviceToken?: string
+}
+```
+
+**AuthKitAccess** (interface)
+```typescript
+interface AuthKitAccess {
+  mode: 'anyone' | 'organisation'
+  domains?: string[]
+  emails?: string[]
+  microsoftTenants?: Record<string, string>
+}
+```
+
 **AppleLoginOptions** (interface)
 ```typescript
 interface AppleLoginOptions {
@@ -4953,6 +4971,8 @@ interface AuthKitConfig {
   collectionIds?: string[]
   identity?: AuthKitIdentity
   signUp?: 'open' | 'invite'
+  access?: AuthKitAccess
+  microsoftClientId?: string
 }
 ```
 
@@ -11937,6 +11957,9 @@ Sign in with LinkedIn (OpenID Connect) via a server-side authorization code (pub
 **appleLogin**(clientId: string, identityToken: string, opts?: AppleLoginOptions) → `Promise<AuthLoginResponse>`
 Sign in with Apple via an Apple identity token (public). Mirrors {@link googleLogin}. On success the returned bearer token is stored automatically and the cache is invalidated. Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`): - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400), `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500) - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this email; the server refuses to silently link. `err.details.requiresEmailVerification` is `true`. Recoverable: the user should sign in with their password (or reset it), then link Apple from settings. **The same 409 can now come back from {@link googleLogin}** under the shared verified-to-verified linking policy. Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape. Pass `opts.trustedDeviceToken` to skip the challenge on a recognized device.
 
+**microsoftLogin**(clientId: string, idToken: string, opts?: MicrosoftLoginOptions) → `Promise<AuthLoginResponse>`
+Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer token is stored and the cache invalidated. Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`) against the app in the public config's `microsoftClientId`. A site on its own domain can't be a registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in page in a popup, which calls this with `opts.returnOrigin` and hands the result back. Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400), `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 — the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409), `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+
 **refreshToken**(clientId: string, refreshToken: string) → `Promise<RefreshResponse>`
 Exchange a refresh token for a fresh access token (public — the refresh token IS the credential). **Native sessions only**; refresh tokens are issued only when the host opted in via `initializeApi({ platform: 'native' })`. On success the new access token is stored automatically (`setBearerToken`). The returned `refreshToken` is **rotated** — the caller must persist it and discard the old one before refreshing again. ⚠️ **Single-use, no retry, serialize calls.** This method issues exactly one request and never retries: replaying a consumed refresh token triggers `REFRESH_TOKEN_REUSE_DETECTED` (the whole session family is revoked). The caller is responsible for ensuring only one refresh is in flight at a time (e.g. across tabs or resume events). Errors (thrown as `SmartlinksApiError`, read via `err.errorCode`): `MISSING_REFRESH_TOKEN` (400), `INVALID_REFRESH_TOKEN` (401), `REFRESH_TOKEN_REUSE_DETECTED` (401) — the last two mean a hard logout.
 

package/dist/docs/auth-kit.md

@@ -259,6 +259,56 @@ try {
 > ⚠️ This is a behaviour change for `googleLogin`, which previously merged silently in
 > this case. Handle the 409 for both methods.
 
+### Sign in with Microsoft
+
+Work or school accounts from **any** organisation, and personal Microsoft accounts (Outlook, Hotmail,
+Live). Add `'microsoft'` to `enabledProviders` — that's all: SmartLinks' own Microsoft app serves every
+organisation, so neither you nor your users' IT registers anything.
+
+```ts
+const session = await authKit.microsoftLogin(clientId, microsoftIdToken, { returnOrigin });
+```
+
+- **In the SmartLinks sign-in UI** the Microsoft button opens SmartLinks' Microsoft sign-in page
+  (`https://smartlinks.app/apps/account/stable/microsoft-proxy.html`) in a popup — the one address
+  registered with Microsoft — which signs in and hands the session back to your site. Your site must be
+  one of the login setup's own (its collections' domains or site addresses, or `allowedRedirectDomains`),
+  else `MICROSOFT_ORIGIN_NOT_ALLOWED` (403).
+- **Your own UI:** get an ID token from Microsoft (`response_type=id_token`, scope `openid profile email`,
+  authority `https://login.microsoftonline.com/common`) for the app in the public config's
+  `microsoftClientId`, and pass it here.
+- **Some companies' IT approves new apps for their staff.** The first person from such a company sees
+  "needs admin approval"; their IT approves SmartLinks once for the organisation and everyone can sign in.
+- **Your own name on Microsoft's screen (optional):** register your own *multitenant* app in Microsoft
+  Entra (Supported account types: any organisation + personal accounts; Web redirect URI as above, with
+  "ID tokens" ticked; token configuration: optional claim `xms_edov` on the ID token) and set its
+  Application (client) ID as `microsoftClientId`.
+- A Microsoft account's email is trusted only when Microsoft vouches that its organisation owns the
+  domain (or for personal accounts): an organisation can give its users any address. Linking to an
+  existing account by email follows the same verified-to-verified rule as Google and Apple.
+
+### Who can sign in (`access`)
+
+Restrict a login setup to one organisation — no keys, no IT:
+
+```ts
+await authKit.update(collectionId, clientId, {
+  access: { mode: 'organisation', domains: ['acme.com'], emails: ['contractor@gmail.com'] },
+});
+```
+
+- Someone is from acme.com when their **verified** email is at acme.com, they're one of `emails`, or they
+  signed in with Microsoft from acme's own Microsoft organisation (looked up from the domain when you
+  save — `microsoftTenants` is filled in for you).
+- Checked on **every** sign-in method each time a session is issued: everyone else gets
+  `NOT_IN_ORGANISATION` (403) with a message naming the domain. Tighten the rule and people already in
+  are refused from their next sign-in.
+- `register` refuses outside addresses before making anything, and never signs an unverified address
+  straight in (even in `immediate` mode) — it must be verified first.
+- Phone-only and WhatsApp-only accounts have no email to prove an organisation, so they can't get in.
+- The public config (`load`) returns `access: { mode, domains }` so your page can say who it's for; the
+  `emails` list is never public. `{ mode: 'anyone' }` (or no `access`) lets everyone in, as before.
+
 ### Refresh tokens (native sessions)
 
 Native/Capacitor hosts can hold long-lived sessions via refresh tokens. Opt in **once**

package/dist/openapi.yaml

@@ -9641,6 +9641,38 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/microsoft:
+    post:
+      tags:
+        - authKit
+      summary: authKit.microsoftLogin
+      operationId: authKit_microsoftLogin
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthLoginResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MicrosoftLoginOptions"
   /authkit/{clientId}/auth/phone/send-code:
     post:
       tags:
@@ -23933,6 +23965,35 @@ components:
           additionalProperties: true
       required:
         - success
+    MicrosoftLoginOptions:
+      type: object
+      properties:
+        returnOrigin:
+          type: string
+        trustedDeviceToken:
+          type: string
+    AuthKitAccess:
+      type: object
+      properties:
+        mode:
+          type: string
+          enum:
+            - anyone
+            - organisation
+        domains:
+          type: array
+          items:
+            type: string
+        emails:
+          type: array
+          items:
+            type: string
+        microsoftTenants:
+          type: object
+          additionalProperties:
+            type: string
+      required:
+        - mode
     AppleLoginOptions:
       type: object
       properties:
@@ -24449,6 +24510,10 @@ components:
           enum:
             - open
             - invite
+        access:
+          $ref: "#/components/schemas/AuthKitAccess"
+        microsoftClientId:
+          type: string
       required:
         - id
     AuthKitInviteRequest:
@@ -24581,6 +24646,7 @@ components:
         - ACCOUNT_EXISTS_UNVERIFIED
         - APPLE_AUTH_FAILED
         - SIGN_UP_CLOSED
+        - NOT_IN_ORGANISATION
     MfaFactor:
       type: string
       enum:

package/dist/types/authKit.d.ts

@@ -98,6 +98,40 @@ export type RefreshErrorCode = 'MISSING_REFRESH_TOKEN' | 'INVALID_REFRESH_TOKEN'
  * Options for {@link authKit.appleLogin}. All fields are optional — only the
  * `identityToken` (passed as a positional argument) is required by the server.
  */
+/** Options for {@link authKit.microsoftLogin}. */
+export interface MicrosoftLoginOptions {
+    /**
+     * The site the session will be handed to, when signing in through a popup page on another address
+     * (the SmartLinks Microsoft sign-in page does this). The server refuses unless it's one of the login
+     * setup's own sites (`MICROSOFT_ORIGIN_NOT_ALLOWED`). Leave it out when signing in on the site itself.
+     */
+    returnOrigin?: string;
+    /** Skip the step-up MFA challenge on a recognised device. */
+    trustedDeviceToken?: string;
+}
+/**
+ * Who can sign in through a login setup, whatever the method (password, magic link, phone, WhatsApp,
+ * Google, Apple, LinkedIn, Microsoft):
+ * - `anyone` (also: no `access`) — anyone, as before;
+ * - `organisation` — people from the listed organisations: a VERIFIED email at one of `domains`, one of
+ *   the listed `emails`, or signing in with Microsoft from the domain's own Microsoft organisation. A
+ *   Microsoft email alone doesn't count (an organisation can give its users any address), so on save
+ *   the server looks up each domain's Microsoft organisation itself — nobody types a tenant id.
+ *
+ * Checked every time a session is issued (tightening it shuts people out from their next sign-in);
+ * refused with `NOT_IN_ORGANISATION` (403). Registration refuses outside addresses up front and never
+ * signs an unverified address straight in. Accounts with no email (phone / WhatsApp only) can't show
+ * they're from an organisation. The public config returns only `{ mode, domains }`.
+ */
+export interface AuthKitAccess {
+    mode: 'anyone' | 'organisation';
+    /** e.g. `['acme.com']` (no `@`; exact domains — list subsidiaries' domains too). Up to 50. */
+    domains?: string[];
+    /** Particular people allowed besides the organisations, e.g. a contractor. Up to 50. Never public. */
+    emails?: string[];
+    /** Server-filled on save: `{ 'acme.com': '<Microsoft tenant id>' }` for domains with a Microsoft organisation. Read-only. */
+    microsoftTenants?: Record<string, string>;
+}
 export interface AppleLoginOptions {
     /** Apple authorization code. Accepted but ignored by the server for now (reserved for future server-side token exchange). */
     authorizationCode?: string;
@@ -128,7 +162,7 @@ export interface AppleLoginOptions {
  * `ACCOUNT_EXISTS_UNVERIFIED` case also carries `requiresEmailVerification: true`
  * in `SmartlinksApiError.details`.
  */
-export type AuthKitErrorCode = 'MISSING_APPLE_TOKEN' | 'APPLE_AUTH_NOT_CONFIGURED' | 'INVALID_APPLE_TOKEN' | 'ACCOUNT_EXISTS_UNVERIFIED' | 'APPLE_AUTH_FAILED' | 'SIGN_UP_CLOSED';
+export type AuthKitErrorCode = 'MISSING_APPLE_TOKEN' | 'APPLE_AUTH_NOT_CONFIGURED' | 'INVALID_APPLE_TOKEN' | 'ACCOUNT_EXISTS_UNVERIFIED' | 'APPLE_AUTH_FAILED' | 'SIGN_UP_CLOSED' | 'NOT_IN_ORGANISATION' | 'MISSING_MICROSOFT_TOKEN' | 'MICROSOFT_AUTH_NOT_CONFIGURED' | 'INVALID_MICROSOFT_TOKEN' | 'MICROSOFT_ORIGIN_NOT_ALLOWED' | 'MICROSOFT_AUTH_FAILED';
 /** A second-step method: a code by email or text message, or from an authenticator app. */
 export type MfaFactor = 'email' | 'sms' | 'totp';
 /**
@@ -445,6 +479,16 @@ export interface AuthKitConfig {
      * Setting `invite` needs own logins first (`OWN_LOGINS_REQUIRED`, 409).
      */
     signUp?: 'open' | 'invite';
+    /** Who can sign in — see {@link AuthKitAccess}. Absent = anyone. */
+    access?: AuthKitAccess;
+    /**
+     * Sign in with Microsoft: add `'microsoft'` to `enabledProviders`. SmartLinks' own Microsoft app serves
+     * every organisation and personal Microsoft accounts, so nothing else is needed. Set this only to show
+     * your OWN name on Microsoft's sign-in screen: the Application (client) ID of your own multitenant app
+     * registration (redirect URI: https://smartlinks.app/apps/account/stable/microsoft-proxy.html). On the
+     * public config it's the effective id (yours, else SmartLinks').
+     */
+    microsoftClientId?: string;
 }
 /** Body of {@link authKit.invite}. */
 export interface AuthKitInviteRequest {

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.12  |  Generated: 2026-11-08T14:30:42.034Z
+Version: 2.1.13  |  Generated: 2026-11-09T11:51:55.948Z
 
 This is a concise summary of all available API functions and types.
 
@@ -4624,6 +4624,24 @@ interface LogoutResponse {
 }
 ```
 
+**MicrosoftLoginOptions** (interface)
+```typescript
+interface MicrosoftLoginOptions {
+  returnOrigin?: string
+  trustedDeviceToken?: string
+}
+```
+
+**AuthKitAccess** (interface)
+```typescript
+interface AuthKitAccess {
+  mode: 'anyone' | 'organisation'
+  domains?: string[]
+  emails?: string[]
+  microsoftTenants?: Record<string, string>
+}
+```
+
 **AppleLoginOptions** (interface)
 ```typescript
 interface AppleLoginOptions {
@@ -4953,6 +4971,8 @@ interface AuthKitConfig {
   collectionIds?: string[]
   identity?: AuthKitIdentity
   signUp?: 'open' | 'invite'
+  access?: AuthKitAccess
+  microsoftClientId?: string
 }
 ```
 
@@ -11937,6 +11957,9 @@ Sign in with LinkedIn (OpenID Connect) via a server-side authorization code (pub
 **appleLogin**(clientId: string, identityToken: string, opts?: AppleLoginOptions) → `Promise<AuthLoginResponse>`
 Sign in with Apple via an Apple identity token (public). Mirrors {@link googleLogin}. On success the returned bearer token is stored automatically and the cache is invalidated. Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`): - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400), `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500) - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this email; the server refuses to silently link. `err.details.requiresEmailVerification` is `true`. Recoverable: the user should sign in with their password (or reset it), then link Apple from settings. **The same 409 can now come back from {@link googleLogin}** under the shared verified-to-verified linking policy. Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape. Pass `opts.trustedDeviceToken` to skip the challenge on a recognized device.
 
+**microsoftLogin**(clientId: string, idToken: string, opts?: MicrosoftLoginOptions) → `Promise<AuthLoginResponse>`
+Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer token is stored and the cache invalidated. Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`) against the app in the public config's `microsoftClientId`. A site on its own domain can't be a registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in page in a popup, which calls this with `opts.returnOrigin` and hands the result back. Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400), `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 — the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409), `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+
 **refreshToken**(clientId: string, refreshToken: string) → `Promise<RefreshResponse>`
 Exchange a refresh token for a fresh access token (public — the refresh token IS the credential). **Native sessions only**; refresh tokens are issued only when the host opted in via `initializeApi({ platform: 'native' })`. On success the new access token is stored automatically (`setBearerToken`). The returned `refreshToken` is **rotated** — the caller must persist it and discard the old one before refreshing again. ⚠️ **Single-use, no retry, serialize calls.** This method issues exactly one request and never retries: replaying a consumed refresh token triggers `REFRESH_TOKEN_REUSE_DETECTED` (the whole session family is revoked). The caller is responsible for ensuring only one refresh is in flight at a time (e.g. across tabs or resume events). Errors (thrown as `SmartlinksApiError`, read via `err.errorCode`): `MISSING_REFRESH_TOKEN` (400), `INVALID_REFRESH_TOKEN` (401), `REFRESH_TOKEN_REUSE_DETECTED` (401) — the last two mean a hard logout.
 

package/docs/auth-kit.md

@@ -259,6 +259,56 @@ try {
 > ⚠️ This is a behaviour change for `googleLogin`, which previously merged silently in
 > this case. Handle the 409 for both methods.
 
+### Sign in with Microsoft
+
+Work or school accounts from **any** organisation, and personal Microsoft accounts (Outlook, Hotmail,
+Live). Add `'microsoft'` to `enabledProviders` — that's all: SmartLinks' own Microsoft app serves every
+organisation, so neither you nor your users' IT registers anything.
+
+```ts
+const session = await authKit.microsoftLogin(clientId, microsoftIdToken, { returnOrigin });
+```
+
+- **In the SmartLinks sign-in UI** the Microsoft button opens SmartLinks' Microsoft sign-in page
+  (`https://smartlinks.app/apps/account/stable/microsoft-proxy.html`) in a popup — the one address
+  registered with Microsoft — which signs in and hands the session back to your site. Your site must be
+  one of the login setup's own (its collections' domains or site addresses, or `allowedRedirectDomains`),
+  else `MICROSOFT_ORIGIN_NOT_ALLOWED` (403).
+- **Your own UI:** get an ID token from Microsoft (`response_type=id_token`, scope `openid profile email`,
+  authority `https://login.microsoftonline.com/common`) for the app in the public config's
+  `microsoftClientId`, and pass it here.
+- **Some companies' IT approves new apps for their staff.** The first person from such a company sees
+  "needs admin approval"; their IT approves SmartLinks once for the organisation and everyone can sign in.
+- **Your own name on Microsoft's screen (optional):** register your own *multitenant* app in Microsoft
+  Entra (Supported account types: any organisation + personal accounts; Web redirect URI as above, with
+  "ID tokens" ticked; token configuration: optional claim `xms_edov` on the ID token) and set its
+  Application (client) ID as `microsoftClientId`.
+- A Microsoft account's email is trusted only when Microsoft vouches that its organisation owns the
+  domain (or for personal accounts): an organisation can give its users any address. Linking to an
+  existing account by email follows the same verified-to-verified rule as Google and Apple.
+
+### Who can sign in (`access`)
+
+Restrict a login setup to one organisation — no keys, no IT:
+
+```ts
+await authKit.update(collectionId, clientId, {
+  access: { mode: 'organisation', domains: ['acme.com'], emails: ['contractor@gmail.com'] },
+});
+```
+
+- Someone is from acme.com when their **verified** email is at acme.com, they're one of `emails`, or they
+  signed in with Microsoft from acme's own Microsoft organisation (looked up from the domain when you
+  save — `microsoftTenants` is filled in for you).
+- Checked on **every** sign-in method each time a session is issued: everyone else gets
+  `NOT_IN_ORGANISATION` (403) with a message naming the domain. Tighten the rule and people already in
+  are refused from their next sign-in.
+- `register` refuses outside addresses before making anything, and never signs an unverified address
+  straight in (even in `immediate` mode) — it must be verified first.
+- Phone-only and WhatsApp-only accounts have no email to prove an organisation, so they can't get in.
+- The public config (`load`) returns `access: { mode, domains }` so your page can say who it's for; the
+  `emails` list is never public. `{ mode: 'anyone' }` (or no `access`) lets everyone in, as before.
+
 ### Refresh tokens (native sessions)
 
 Native/Capacitor hosts can hold long-lived sessions via refresh tokens. Opt in **once**

package/openapi.yaml

@@ -9641,6 +9641,38 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/microsoft:
+    post:
+      tags:
+        - authKit
+      summary: authKit.microsoftLogin
+      operationId: authKit_microsoftLogin
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthLoginResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MicrosoftLoginOptions"
   /authkit/{clientId}/auth/phone/send-code:
     post:
       tags:
@@ -23933,6 +23965,35 @@ components:
           additionalProperties: true
       required:
         - success
+    MicrosoftLoginOptions:
+      type: object
+      properties:
+        returnOrigin:
+          type: string
+        trustedDeviceToken:
+          type: string
+    AuthKitAccess:
+      type: object
+      properties:
+        mode:
+          type: string
+          enum:
+            - anyone
+            - organisation
+        domains:
+          type: array
+          items:
+            type: string
+        emails:
+          type: array
+          items:
+            type: string
+        microsoftTenants:
+          type: object
+          additionalProperties:
+            type: string
+      required:
+        - mode
     AppleLoginOptions:
       type: object
       properties:
@@ -24449,6 +24510,10 @@ components:
           enum:
             - open
             - invite
+        access:
+          $ref: "#/components/schemas/AuthKitAccess"
+        microsoftClientId:
+          type: string
       required:
         - id
     AuthKitInviteRequest:
@@ -24581,6 +24646,7 @@ components:
         - ACCOUNT_EXISTS_UNVERIFIED
         - APPLE_AUTH_FAILED
         - SIGN_UP_CLOSED
+        - NOT_IN_ORGANISATION
     MfaFactor:
       type: string
       enum:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.1.12",
+  "version": "2.1.13",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",