archastro.platform.auth

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 4cece1e1b7b8
  4
  5from __future__ import annotations
  6
  7from dataclasses import dataclass
  8
  9from .runtime.http_client import HttpClient, SyncHttpClient
 10
 11
 12@dataclass
 13class AuthTokens:
 14    token_expiry: int | None = None
 15    refresh_token: str | None = None
 16    access_token: str | None = None
 17
 18
 19class AsyncAuthClient:
 20    def __init__(self, http: HttpClient):
 21        self._http = http
 22
 23    async def allowed_auth_methods(self) -> dict:
 24        """
 25        List supported auth methods
 26        Returns the complete catalogue of authentication methods the platform supports,
 27        including each method's stable slug, user-facing name, and description.
 28        Use this endpoint to render method labels in sign-in UIs or org settings screens
 29        without hardcoding copy or maintaining your own enum list. Results reflect the
 30        platform's source-of-truth catalogue and are consistent across all orgs.
 31        This endpoint requires only a publishable key and is accessible without an active
 32        user session, making it suitable for pre-authentication flows such as login page
 33        rendering or onboarding configuration.
 34
 35        Returns:
 36            Successful response
 37        """
 38        data = await self._http.request(
 39            "/api/v1/auth/allowed_auth_methods",
 40            method="GET",
 41        )
 42        return data
 43
 44    async def login(self, email: str, password: str) -> AuthTokens:
 45        """
 46        Authenticate with email and password
 47        Authenticates a user with an email address and password and returns a short-lived
 48        access token, a refresh token, and the authenticated user object. Use the refresh
 49        token with the `/auth/refresh` endpoint to obtain new access tokens without
 50        re-authenticating.
 51        Password login must be enabled for the app; apps that have disabled password
 52        authentication return HTTP 403. Requests are rate-limited per IP (10 per minute)
 53        and per email-IP pair (5 per minute) exceeding either limit returns HTTP 429.
 54
 55        Args:
 56            email: Email address of the user to authenticate.
 57            password: Password for the account associated with the given email.
 58
 59        Returns:
 60            Access token, refresh token, and authenticated user object.
 61        """
 62        body: dict[str, object] = {}
 63        body["email"] = email
 64        body["password"] = password
 65
 66        data = await self._http.request(
 67            "/api/v1/auth/login",
 68            method="POST",
 69            body=body,
 70        )
 71        return AuthTokens(
 72            token_expiry=data.get("expires_in"),
 73            refresh_token=data.get("refresh_token"),
 74            access_token=data.get("token"),
 75        )
 76
 77    async def request_login_magic_link(
 78        self, email: str | None = None, redirect_uri: str | None = None
 79    ) -> dict:
 80        """
 81        Request a magic link for login
 82        Sends a magic link to the given email address so an existing user can sign in
 83        without a password. The user clicks the link in their email and is redirected to
 84        `redirect_uri` with a token; pass that token to `/api/v1/auth/verify/link` to obtain
 85        session tokens.
 86        If no account exists for the email, the endpoint still returns success to prevent
 87        email enumeration no link is sent in that case. Both `email` and `redirect_uri`
 88        are required. Requests are rate-limited per IP (10 per minute) and per email-IP pair
 89        (3 per minute) exceeding either limit returns HTTP 429. Returns HTTP 204 on success.
 90
 91        Args:
 92            email: Email address of the account to send the magic link to.
 93            redirect_uri: URL the user is redirected to after clicking the magic link. The token is appended as a query parameter.
 94
 95        Returns:
 96            No content
 97        """
 98        body: dict[str, object] = {}
 99        if email is not None:
100            body["email"] = email
101        if redirect_uri is not None:
102            body["redirect_uri"] = redirect_uri
103
104        data = await self._http.request(
105            "/api/v1/auth/login/link",
106            method="POST",
107            body=body,
108        )
109        return data
110
111    async def refresh(self, refresh_token: str) -> AuthTokens:
112        """
113        Refresh an access token
114        Exchanges a valid refresh token for a new access token and a new refresh token,
115        rotating the refresh token on every call. The response also includes the updated
116        user object. Store the new refresh token and discard the old one.
117        Refresh tokens are single-use submitting an already-consumed token returns HTTP 401.
118        Rate limiting is applied per (user, IP) pair when the token can be verified, and
119        falls back to IP-only when it cannot. The limit is 30 exchanges per minute per
120        bucket; exceeding it returns HTTP 429.
121
122        Args:
123            refresh_token: Refresh token previously issued by a login, registration, or token-refresh response.
124
125        Returns:
126            New access token, new refresh token, and the authenticated user object.
127        """
128        body: dict[str, object] = {}
129        body["refresh_token"] = refresh_token
130
131        data = await self._http.request(
132            "/api/v1/auth/refresh",
133            method="POST",
134            body=body,
135        )
136        return AuthTokens(
137            token_expiry=data.get("expires_in"),
138            refresh_token=data.get("refresh_token"),
139            access_token=data.get("token"),
140        )
141
142    async def register(
143        self,
144        email: str,
145        alias: str | None = None,
146        full_name: str | None = None,
147        invite_code: str | None = None,
148        password: str | None = None,
149        set_org: str | None = None,
150        team_invite: str | None = None,
151        timezone: str | None = None,
152    ) -> AuthTokens:
153        """
154        Register a new user with email and password
155        Creates a new user account and returns an access token, refresh token, and the new
156        user object. Two registration paths are supported:
157        - **Team registration**: supply `team_invite` with a valid team invite ID. The new
158        user is added to that team immediately upon registration. Returns HTTP 404 if the
159        invite is not found.
160        - **Standard registration**: supply `password`. An `invite_code` may optionally be
161        included for invite-gated apps; an invalid code returns HTTP 404.
162        Provide `team_invite` or `password`; when both are supplied, team registration
163        takes precedence. Omitting both returns HTTP 400. Unknown fields return HTTP 400
164        with field-level guidance. Use `full_name` for the profile name (returned as
165        `user.name`); `name` is not an input field. `alias` is a separate optional handle.
166        Legacy `team_invite_id` remains accepted; `team_invite` takes precedence.
167        Password registration must be enabled for the app; disabled apps return
168        HTTP 403. The response status is HTTP 201 on success.
169
170        Args:
171            email: Email address for the new account.
172            alias: Display alias (handle) for the new account.
173            full_name: Full name for the new account.
174            invite_code: Invite code for invite-gated registration. Applied only in the standard registration path.
175            password: Password for the new account. Required for standard (non-team-invite) registration.
176            set_org: Create or reuse an organization from the work-email domain and stamp the new user into it.
177            team_invite: Team invite ID. When provided, the user is added to the team on registration.
178            timezone: IANA timezone name for the new account, e.g. `"America/New_York"`.
179
180        Returns:
181            Access token, refresh token, and the newly created user object.
182        """
183        body: dict[str, object] = {}
184        body["email"] = email
185        if alias is not None:
186            body["alias"] = alias
187        if full_name is not None:
188            body["full_name"] = full_name
189        if invite_code is not None:
190            body["invite_code"] = invite_code
191        if password is not None:
192            body["password"] = password
193        if set_org is not None:
194            body["set_org"] = set_org
195        if team_invite is not None:
196            body["team_invite"] = team_invite
197        if timezone is not None:
198            body["timezone"] = timezone
199
200        data = await self._http.request(
201            "/api/v1/auth/register",
202            method="POST",
203            body=body,
204        )
205        return AuthTokens(
206            token_expiry=data.get("expires_in"),
207            refresh_token=data.get("refresh_token"),
208            access_token=data.get("token"),
209        )
210
211    async def request_register_magic_link(
212        self,
213        alias: str | None = None,
214        email: str | None = None,
215        full_name: str | None = None,
216        org: str | None = None,
217        redirect_uri: str | None = None,
218        set_org: str | None = None,
219        timezone: str | None = None,
220    ) -> dict:
221        """
222        Request a magic link for registration
223        Starts a passwordless registration flow by sending a verification link to the given
224        email address. The recipient clicks the link and is redirected to `redirect_uri` with
225        a token; pass that token to `/api/v1/auth/verify/link` to complete registration and obtain
226        session tokens.
227        Profile fields (`full_name`, `alias`, `timezone`) and, with `set_org`, the `org`
228        details are captured now and applied when the link is verified; nothing is created
229        before the click. Requests are rate-limited per IP (10 per minute) and per
230        email-IP pair (3 per minute) exceeding either limit returns HTTP 429. Returns
231        HTTP 204 on success.
232
233        Args:
234            alias: Display alias (handle) for the new account.
235            email: Email address to send the registration magic link to.
236            full_name: Full name for the new account.
237            org: Company details for the organization a `set_org` registration creates at confirmation. Ignored when the domain org already exists or the mailbox is personal (which keeps the platform's own identity and takes only the sign-in methods).
238            redirect_uri: URL the user is redirected to after clicking the registration link. The token is appended as a query parameter.
239            set_org: Create or reuse an organization from the work-email domain during confirmation.
240            timezone: IANA timezone name for the new account, e.g. `"America/New_York"`.
241
242        Returns:
243            No content
244        """
245        body: dict[str, object] = {}
246        if alias is not None:
247            body["alias"] = alias
248        if email is not None:
249            body["email"] = email
250        if full_name is not None:
251            body["full_name"] = full_name
252        if org is not None:
253            body["org"] = org
254        if redirect_uri is not None:
255            body["redirect_uri"] = redirect_uri
256        if set_org is not None:
257            body["set_org"] = set_org
258        if timezone is not None:
259            body["timezone"] = timezone
260
261        data = await self._http.request(
262            "/api/v1/auth/register/link",
263            method="POST",
264            body=body,
265        )
266        return data
267
268    async def request_magic_link(
269        self,
270        email: str | None = None,
271        full_name: str | None = None,
272        mcp_client_id: str | None = None,
273        org: str | None = None,
274        redirect_uri: str | None = None,
275        set_org: str | None = None,
276        signup_origin: str | None = None,
277    ) -> dict:
278        """
279        Request a magic link for login or registration
280        Sends a passwordless magic link to the given email address. If an account with that
281        email already exists, a login link is sent. If no account exists, a registration link
282        is sent and the recipient completes sign-up by clicking through. This unified endpoint
283        lets you implement a single email-entry UI that handles both cases transparently.
284        The `redirect_uri` is validated against the app's registered hosts; an unregistered
285        URI returns HTTP 400. Both `email` and `redirect_uri` are required. Requests are
286        rate-limited per IP (10 per minute) and per email-IP pair (3 per minute). Returns
287        HTTP 204 on success no body. If the app has Allowed Users enabled and the
288        address is not on the list, returns HTTP 403 `user_not_allowed`. That refusal
289        is the same for new and existing addresses, so it does not reveal whether an
290        account exists.
291        For a new user, `full_name` and (with `set_org`) the `org` details ride the pending
292        registration and are applied when the link is verified; nothing is created before
293        the click. They are ignored when the email already belongs to a user. Malformed
294        values return HTTP 422 before the address is looked up, so the response cannot
295        reveal whether an account exists.
296
297        Args:
298            email: Email address to send the magic link to.
299            full_name: Display name for the account the verified link will create.
300            mcp_client_id: Opaque dynamic-registration client id for an MCP consent signup. Platform resolves it to a closed analytics key.
301            org: Company details for the organization a `set_org` registration creates at confirmation. Ignored when the domain org already exists or the mailbox is personal (which keeps the platform's own identity and takes only the sign-in methods).
302            redirect_uri: URL the user is redirected to after clicking the magic link. Must be registered with the app.
303            set_org: For a new user, create or reuse an organization from the work-email domain during confirmation.
304            signup_origin: Closed product intent for a new signup. Missing or unknown values become generic and never affect authentication.
305
306        Returns:
307            No content
308        """
309        body: dict[str, object] = {}
310        if email is not None:
311            body["email"] = email
312        if full_name is not None:
313            body["full_name"] = full_name
314        if mcp_client_id is not None:
315            body["mcp_client_id"] = mcp_client_id
316        if org is not None:
317            body["org"] = org
318        if redirect_uri is not None:
319            body["redirect_uri"] = redirect_uri
320        if set_org is not None:
321            body["set_org"] = set_org
322        if signup_origin is not None:
323            body["signup_origin"] = signup_origin
324
325        data = await self._http.request(
326            "/api/v1/auth/request/link",
327            method="POST",
328            body=body,
329        )
330        return data
331
332    async def exchange_login_token(self, token: str, timezone: str | None = None) -> AuthTokens:
333        """
334        Exchange a one-time login token for session tokens
335        Exchanges an email-login token (including email reply links) or an internal
336        impersonation login token for session credentials. Passwordless magic-link tokens
337        from `/api/v1/auth/login/link`, `/api/v1/auth/register/link`, or
338        `/api/v1/auth/request/link` must instead go to `/api/v1/auth/verify/link`.
339        Numeric email codes go to `/api/v1/auth/code/verify` with `email` and `code`.
340        Access and refresh tokens are not accepted here. Invalid, expired, or already-used
341        login tokens return HTTP 401 with structured `error.type`, `error.code`, and
342        `error.message` fields.
343        If `timezone` is provided and the user's current timezone is still the default
344        (`"America/Los_Angeles"`), the account timezone is updated in the same request.
345        Requests are rate-limited to 10 per IP per minute; exceeding this returns HTTP 429.
346
347        Args:
348            token: Single-use email-login or impersonation token; not a passwordless magic-link token or numeric code.
349            timezone: IANA timezone name to apply to the account if the account timezone is still the default, e.g. `"Europe/London"`. Omit to leave the timezone unchanged.
350
351        Returns:
352            Access token, refresh token, and the authenticated user object.
353        """
354        body: dict[str, object] = {}
355        body["token"] = token
356        if timezone is not None:
357            body["timezone"] = timezone
358
359        data = await self._http.request(
360            "/api/v1/auth/token",
361            method="POST",
362            body=body,
363        )
364        return AuthTokens(
365            token_expiry=data.get("expires_in"),
366            refresh_token=data.get("refresh_token"),
367            access_token=data.get("token"),
368        )
369
370    async def verify_magic_link(self, token: str | None = None) -> AuthTokens:
371        """
372        Verify a magic link token
373        Consumes a single-use token from a magic link URL and returns an access token,
374        refresh token, and the authenticated user object. This endpoint completes both the
375        login flow (initiated by `/api/v1/auth/login/link`) and the registration flow
376        (initiated by `/api/v1/auth/register/link` or `/api/v1/auth/request/link`).
377        Extract the token from the `token` query parameter of the magic link redirect URI
378        and POST JSON `{"token":"<token from redirect URI>"}` to
379        `/api/v1/auth/verify/link`, not `/api/v1/auth/token`. Expired or already-used tokens return HTTP 401 expired links
380        have `error.code` = `authentication_error` and `error.message` =
381        `expired_token`; unknown or already-used tokens have `error.message` =
382        `invalid_or_expired_token`. If the app has disabled passwordless authentication
383        the request returns HTTP 403. Rate-limited to 10 requests per IP per minute
384        exceeding this returns HTTP 429.
385
386        Args:
387            token: Single-use magic link token extracted from the redirect URI query parameter.
388
389        Returns:
390            Access token, refresh token, and the authenticated user object.
391        """
392        body: dict[str, object] = {}
393        if token is not None:
394            body["token"] = token
395
396        data = await self._http.request(
397            "/api/v1/auth/verify/link",
398            method="POST",
399            body=body,
400        )
401        return AuthTokens(
402            token_expiry=data.get("expires_in"),
403            refresh_token=data.get("refresh_token"),
404            access_token=data.get("token"),
405        )
406
407
408class AuthClient:
409    def __init__(self, http: SyncHttpClient):
410        self._http = http
411
412    def allowed_auth_methods(self) -> dict:
413        """
414        List supported auth methods
415        Returns the complete catalogue of authentication methods the platform supports,
416        including each method's stable slug, user-facing name, and description.
417        Use this endpoint to render method labels in sign-in UIs or org settings screens
418        without hardcoding copy or maintaining your own enum list. Results reflect the
419        platform's source-of-truth catalogue and are consistent across all orgs.
420        This endpoint requires only a publishable key and is accessible without an active
421        user session, making it suitable for pre-authentication flows such as login page
422        rendering or onboarding configuration.
423
424        Returns:
425            Successful response
426        """
427        data = self._http.request(
428            "/api/v1/auth/allowed_auth_methods",
429            method="GET",
430        )
431        return data
432
433    def login(self, email: str, password: str) -> AuthTokens:
434        """
435        Authenticate with email and password
436        Authenticates a user with an email address and password and returns a short-lived
437        access token, a refresh token, and the authenticated user object. Use the refresh
438        token with the `/auth/refresh` endpoint to obtain new access tokens without
439        re-authenticating.
440        Password login must be enabled for the app; apps that have disabled password
441        authentication return HTTP 403. Requests are rate-limited per IP (10 per minute)
442        and per email-IP pair (5 per minute) exceeding either limit returns HTTP 429.
443
444        Args:
445            email: Email address of the user to authenticate.
446            password: Password for the account associated with the given email.
447
448        Returns:
449            Access token, refresh token, and authenticated user object.
450        """
451        body: dict[str, object] = {}
452        body["email"] = email
453        body["password"] = password
454
455        data = self._http.request(
456            "/api/v1/auth/login",
457            method="POST",
458            body=body,
459        )
460        return AuthTokens(
461            token_expiry=data.get("expires_in"),
462            refresh_token=data.get("refresh_token"),
463            access_token=data.get("token"),
464        )
465
466    def request_login_magic_link(
467        self, email: str | None = None, redirect_uri: str | None = None
468    ) -> dict:
469        """
470        Request a magic link for login
471        Sends a magic link to the given email address so an existing user can sign in
472        without a password. The user clicks the link in their email and is redirected to
473        `redirect_uri` with a token; pass that token to `/api/v1/auth/verify/link` to obtain
474        session tokens.
475        If no account exists for the email, the endpoint still returns success to prevent
476        email enumeration no link is sent in that case. Both `email` and `redirect_uri`
477        are required. Requests are rate-limited per IP (10 per minute) and per email-IP pair
478        (3 per minute) exceeding either limit returns HTTP 429. Returns HTTP 204 on success.
479
480        Args:
481            email: Email address of the account to send the magic link to.
482            redirect_uri: URL the user is redirected to after clicking the magic link. The token is appended as a query parameter.
483
484        Returns:
485            No content
486        """
487        body: dict[str, object] = {}
488        if email is not None:
489            body["email"] = email
490        if redirect_uri is not None:
491            body["redirect_uri"] = redirect_uri
492
493        data = self._http.request(
494            "/api/v1/auth/login/link",
495            method="POST",
496            body=body,
497        )
498        return data
499
500    def refresh(self, refresh_token: str) -> AuthTokens:
501        """
502        Refresh an access token
503        Exchanges a valid refresh token for a new access token and a new refresh token,
504        rotating the refresh token on every call. The response also includes the updated
505        user object. Store the new refresh token and discard the old one.
506        Refresh tokens are single-use submitting an already-consumed token returns HTTP 401.
507        Rate limiting is applied per (user, IP) pair when the token can be verified, and
508        falls back to IP-only when it cannot. The limit is 30 exchanges per minute per
509        bucket; exceeding it returns HTTP 429.
510
511        Args:
512            refresh_token: Refresh token previously issued by a login, registration, or token-refresh response.
513
514        Returns:
515            New access token, new refresh token, and the authenticated user object.
516        """
517        body: dict[str, object] = {}
518        body["refresh_token"] = refresh_token
519
520        data = self._http.request(
521            "/api/v1/auth/refresh",
522            method="POST",
523            body=body,
524        )
525        return AuthTokens(
526            token_expiry=data.get("expires_in"),
527            refresh_token=data.get("refresh_token"),
528            access_token=data.get("token"),
529        )
530
531    def register(
532        self,
533        email: str,
534        alias: str | None = None,
535        full_name: str | None = None,
536        invite_code: str | None = None,
537        password: str | None = None,
538        set_org: str | None = None,
539        team_invite: str | None = None,
540        timezone: str | None = None,
541    ) -> AuthTokens:
542        """
543        Register a new user with email and password
544        Creates a new user account and returns an access token, refresh token, and the new
545        user object. Two registration paths are supported:
546        - **Team registration**: supply `team_invite` with a valid team invite ID. The new
547        user is added to that team immediately upon registration. Returns HTTP 404 if the
548        invite is not found.
549        - **Standard registration**: supply `password`. An `invite_code` may optionally be
550        included for invite-gated apps; an invalid code returns HTTP 404.
551        Provide `team_invite` or `password`; when both are supplied, team registration
552        takes precedence. Omitting both returns HTTP 400. Unknown fields return HTTP 400
553        with field-level guidance. Use `full_name` for the profile name (returned as
554        `user.name`); `name` is not an input field. `alias` is a separate optional handle.
555        Legacy `team_invite_id` remains accepted; `team_invite` takes precedence.
556        Password registration must be enabled for the app; disabled apps return
557        HTTP 403. The response status is HTTP 201 on success.
558
559        Args:
560            email: Email address for the new account.
561            alias: Display alias (handle) for the new account.
562            full_name: Full name for the new account.
563            invite_code: Invite code for invite-gated registration. Applied only in the standard registration path.
564            password: Password for the new account. Required for standard (non-team-invite) registration.
565            set_org: Create or reuse an organization from the work-email domain and stamp the new user into it.
566            team_invite: Team invite ID. When provided, the user is added to the team on registration.
567            timezone: IANA timezone name for the new account, e.g. `"America/New_York"`.
568
569        Returns:
570            Access token, refresh token, and the newly created user object.
571        """
572        body: dict[str, object] = {}
573        body["email"] = email
574        if alias is not None:
575            body["alias"] = alias
576        if full_name is not None:
577            body["full_name"] = full_name
578        if invite_code is not None:
579            body["invite_code"] = invite_code
580        if password is not None:
581            body["password"] = password
582        if set_org is not None:
583            body["set_org"] = set_org
584        if team_invite is not None:
585            body["team_invite"] = team_invite
586        if timezone is not None:
587            body["timezone"] = timezone
588
589        data = self._http.request(
590            "/api/v1/auth/register",
591            method="POST",
592            body=body,
593        )
594        return AuthTokens(
595            token_expiry=data.get("expires_in"),
596            refresh_token=data.get("refresh_token"),
597            access_token=data.get("token"),
598        )
599
600    def request_register_magic_link(
601        self,
602        alias: str | None = None,
603        email: str | None = None,
604        full_name: str | None = None,
605        org: str | None = None,
606        redirect_uri: str | None = None,
607        set_org: str | None = None,
608        timezone: str | None = None,
609    ) -> dict:
610        """
611        Request a magic link for registration
612        Starts a passwordless registration flow by sending a verification link to the given
613        email address. The recipient clicks the link and is redirected to `redirect_uri` with
614        a token; pass that token to `/api/v1/auth/verify/link` to complete registration and obtain
615        session tokens.
616        Profile fields (`full_name`, `alias`, `timezone`) and, with `set_org`, the `org`
617        details are captured now and applied when the link is verified; nothing is created
618        before the click. Requests are rate-limited per IP (10 per minute) and per
619        email-IP pair (3 per minute) exceeding either limit returns HTTP 429. Returns
620        HTTP 204 on success.
621
622        Args:
623            alias: Display alias (handle) for the new account.
624            email: Email address to send the registration magic link to.
625            full_name: Full name for the new account.
626            org: Company details for the organization a `set_org` registration creates at confirmation. Ignored when the domain org already exists or the mailbox is personal (which keeps the platform's own identity and takes only the sign-in methods).
627            redirect_uri: URL the user is redirected to after clicking the registration link. The token is appended as a query parameter.
628            set_org: Create or reuse an organization from the work-email domain during confirmation.
629            timezone: IANA timezone name for the new account, e.g. `"America/New_York"`.
630
631        Returns:
632            No content
633        """
634        body: dict[str, object] = {}
635        if alias is not None:
636            body["alias"] = alias
637        if email is not None:
638            body["email"] = email
639        if full_name is not None:
640            body["full_name"] = full_name
641        if org is not None:
642            body["org"] = org
643        if redirect_uri is not None:
644            body["redirect_uri"] = redirect_uri
645        if set_org is not None:
646            body["set_org"] = set_org
647        if timezone is not None:
648            body["timezone"] = timezone
649
650        data = self._http.request(
651            "/api/v1/auth/register/link",
652            method="POST",
653            body=body,
654        )
655        return data
656
657    def request_magic_link(
658        self,
659        email: str | None = None,
660        full_name: str | None = None,
661        mcp_client_id: str | None = None,
662        org: str | None = None,
663        redirect_uri: str | None = None,
664        set_org: str | None = None,
665        signup_origin: str | None = None,
666    ) -> dict:
667        """
668        Request a magic link for login or registration
669        Sends a passwordless magic link to the given email address. If an account with that
670        email already exists, a login link is sent. If no account exists, a registration link
671        is sent and the recipient completes sign-up by clicking through. This unified endpoint
672        lets you implement a single email-entry UI that handles both cases transparently.
673        The `redirect_uri` is validated against the app's registered hosts; an unregistered
674        URI returns HTTP 400. Both `email` and `redirect_uri` are required. Requests are
675        rate-limited per IP (10 per minute) and per email-IP pair (3 per minute). Returns
676        HTTP 204 on success no body. If the app has Allowed Users enabled and the
677        address is not on the list, returns HTTP 403 `user_not_allowed`. That refusal
678        is the same for new and existing addresses, so it does not reveal whether an
679        account exists.
680        For a new user, `full_name` and (with `set_org`) the `org` details ride the pending
681        registration and are applied when the link is verified; nothing is created before
682        the click. They are ignored when the email already belongs to a user. Malformed
683        values return HTTP 422 before the address is looked up, so the response cannot
684        reveal whether an account exists.
685
686        Args:
687            email: Email address to send the magic link to.
688            full_name: Display name for the account the verified link will create.
689            mcp_client_id: Opaque dynamic-registration client id for an MCP consent signup. Platform resolves it to a closed analytics key.
690            org: Company details for the organization a `set_org` registration creates at confirmation. Ignored when the domain org already exists or the mailbox is personal (which keeps the platform's own identity and takes only the sign-in methods).
691            redirect_uri: URL the user is redirected to after clicking the magic link. Must be registered with the app.
692            set_org: For a new user, create or reuse an organization from the work-email domain during confirmation.
693            signup_origin: Closed product intent for a new signup. Missing or unknown values become generic and never affect authentication.
694
695        Returns:
696            No content
697        """
698        body: dict[str, object] = {}
699        if email is not None:
700            body["email"] = email
701        if full_name is not None:
702            body["full_name"] = full_name
703        if mcp_client_id is not None:
704            body["mcp_client_id"] = mcp_client_id
705        if org is not None:
706            body["org"] = org
707        if redirect_uri is not None:
708            body["redirect_uri"] = redirect_uri
709        if set_org is not None:
710            body["set_org"] = set_org
711        if signup_origin is not None:
712            body["signup_origin"] = signup_origin
713
714        data = self._http.request(
715            "/api/v1/auth/request/link",
716            method="POST",
717            body=body,
718        )
719        return data
720
721    def exchange_login_token(self, token: str, timezone: str | None = None) -> AuthTokens:
722        """
723        Exchange a one-time login token for session tokens
724        Exchanges an email-login token (including email reply links) or an internal
725        impersonation login token for session credentials. Passwordless magic-link tokens
726        from `/api/v1/auth/login/link`, `/api/v1/auth/register/link`, or
727        `/api/v1/auth/request/link` must instead go to `/api/v1/auth/verify/link`.
728        Numeric email codes go to `/api/v1/auth/code/verify` with `email` and `code`.
729        Access and refresh tokens are not accepted here. Invalid, expired, or already-used
730        login tokens return HTTP 401 with structured `error.type`, `error.code`, and
731        `error.message` fields.
732        If `timezone` is provided and the user's current timezone is still the default
733        (`"America/Los_Angeles"`), the account timezone is updated in the same request.
734        Requests are rate-limited to 10 per IP per minute; exceeding this returns HTTP 429.
735
736        Args:
737            token: Single-use email-login or impersonation token; not a passwordless magic-link token or numeric code.
738            timezone: IANA timezone name to apply to the account if the account timezone is still the default, e.g. `"Europe/London"`. Omit to leave the timezone unchanged.
739
740        Returns:
741            Access token, refresh token, and the authenticated user object.
742        """
743        body: dict[str, object] = {}
744        body["token"] = token
745        if timezone is not None:
746            body["timezone"] = timezone
747
748        data = self._http.request(
749            "/api/v1/auth/token",
750            method="POST",
751            body=body,
752        )
753        return AuthTokens(
754            token_expiry=data.get("expires_in"),
755            refresh_token=data.get("refresh_token"),
756            access_token=data.get("token"),
757        )
758
759    def verify_magic_link(self, token: str | None = None) -> AuthTokens:
760        """
761        Verify a magic link token
762        Consumes a single-use token from a magic link URL and returns an access token,
763        refresh token, and the authenticated user object. This endpoint completes both the
764        login flow (initiated by `/api/v1/auth/login/link`) and the registration flow
765        (initiated by `/api/v1/auth/register/link` or `/api/v1/auth/request/link`).
766        Extract the token from the `token` query parameter of the magic link redirect URI
767        and POST JSON `{"token":"<token from redirect URI>"}` to
768        `/api/v1/auth/verify/link`, not `/api/v1/auth/token`. Expired or already-used tokens return HTTP 401 expired links
769        have `error.code` = `authentication_error` and `error.message` =
770        `expired_token`; unknown or already-used tokens have `error.message` =
771        `invalid_or_expired_token`. If the app has disabled passwordless authentication
772        the request returns HTTP 403. Rate-limited to 10 requests per IP per minute
773        exceeding this returns HTTP 429.
774
775        Args:
776            token: Single-use magic link token extracted from the redirect URI query parameter.
777
778        Returns:
779            Access token, refresh token, and the authenticated user object.
780        """
781        body: dict[str, object] = {}
782        if token is not None:
783            body["token"] = token
784
785        data = self._http.request(
786            "/api/v1/auth/verify/link",
787            method="POST",
788            body=body,
789        )
790        return AuthTokens(
791            token_expiry=data.get("expires_in"),
792            refresh_token=data.get("refresh_token"),
793            access_token=data.get("token"),
794        )