@spec allowed_auth_methods(ArchAstro.Client.t()) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1AuthAllowedAuthMethods.Response.t()}
  | {:error, ArchAstro.Error.reason()}

List supported auth methods

Returns the complete catalogue of authentication methods the platform supports, including each method's stable slug, user-facing name, and description.

Use this endpoint to render method labels in sign-in UIs or org settings screens without hardcoding copy or maintaining your own enum list. Results reflect the platform's source-of-truth catalogue and are consistent across all orgs.

This endpoint requires only a publishable key and is accessible without an active user session, making it suitable for pre-authentication flows such as login page rendering or onboarding configuration.

@spec exchange_login_token(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AuthToken.AuthInput.t()
) :: {:ok, ArchAstro.Types.AuthTokens.t()} | {:error, ArchAstro.Error.reason()}

Exchange a one-time login token for session tokens

Consumes a single-use login token delivered via email and returns an access token, refresh token, and the authenticated user object. One-time tokens are issued by the passwordless login flow and expire after a short window; submitting an expired or already-used token returns HTTP 401.

If timezone is provided and the user's current timezone is still the default ("America/Los_Angeles"), the account timezone is updated in the same request. Requests are rate-limited to 10 per IP per minute; exceeding this returns HTTP 429.

@spec login(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AuthLogin.AuthInput.t()
) ::
  {:ok, ArchAstro.Types.AuthTokens.t()} | {:error, ArchAstro.Error.reason()}

Authenticate with email and password

Authenticates a user with an email address and password and returns a short-lived access token, a refresh token, and the authenticated user object. Use the refresh token with the /auth/refresh endpoint to obtain new access tokens without re-authenticating.

Password login must be enabled for the app; apps that have disabled password authentication return HTTP 403. Requests are rate-limited per IP (10 per minute) and per email-IP pair (5 per minute) — exceeding either limit returns HTTP 429.

@spec refresh(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AuthRefresh.AuthInput.t()
) ::
  {:ok, ArchAstro.Types.AuthTokens.t()} | {:error, ArchAstro.Error.reason()}

Refresh an access token

Exchanges a valid refresh token for a new access token and a new refresh token, rotating the refresh token on every call. The response also includes the updated user object. Store the new refresh token and discard the old one.

Refresh tokens are single-use — submitting an already-consumed token returns HTTP 401. Rate limiting is applied per (user, IP) pair when the token can be verified, and falls back to IP-only when it cannot. The limit is 30 exchanges per minute per bucket; exceeding it returns HTTP 429.

@spec register(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AuthRegister.AuthInput.t()
) :: {:ok, ArchAstro.Types.AuthTokens.t()} | {:error, ArchAstro.Error.reason()}

Register a new user with email and password

Creates a new user account and returns an access token, refresh token, and the new user object. Two registration paths are supported:

• Team registration: supply team_invite with a valid team invite ID. The new user is added to that team immediately upon registration. Returns HTTP 404 if the invite is not found.
• Standard registration: supply password. An invite_code may optionally be included for invite-gated apps; an invalid code returns HTTP 404.

Exactly one of team_invite or password must be provided; omitting both returns HTTP 400. Password registration must be enabled for the app; disabled apps return HTTP 403. The response status is HTTP 201 on success.

@spec request_login_magic_link(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AuthLoginLink.AuthInput.t()
) :: {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Request a magic link for login

Sends a magic link to the given email address so an existing user can sign in without a password. The user clicks the link in their email and is redirected to redirect_uri with a token; pass that token to /auth/verify_link to obtain session tokens.

If no account exists for the email, the endpoint still returns success to prevent email enumeration — no link is sent in that case. Both email and redirect_uri are required. Requests are rate-limited per IP (10 per minute) and per email-IP pair (3 per minute) — exceeding either limit returns HTTP 429. Returns HTTP 204 on success.

@spec request_magic_link(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AuthRequestLink.AuthInput.t()
) :: {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Request a magic link for login or registration

Sends a passwordless magic link to the given email address. If an account with that email already exists, a login link is sent. If no account exists, a registration link is sent and the recipient completes sign-up by clicking through. This unified endpoint lets you implement a single email-entry UI that handles both cases transparently.

The redirect_uri is validated against the app's registered hosts; an unregistered URI returns HTTP 400. Both email and redirect_uri are required. Requests are rate-limited per IP (10 per minute) and per email-IP pair (3 per minute). Returns HTTP 204 on success — no body.

@spec request_register_magic_link(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AuthRegisterLink.AuthInput.t()
) :: {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Request a magic link for registration

Starts a passwordless registration flow by sending a verification link to the given email address. The recipient clicks the link and is redirected to redirect_uri with a token; pass that token to /auth/verify_link to complete registration and obtain session tokens.

Profile fields (full_name, alias, timezone) are captured now and applied when the link is verified. Requests are rate-limited per IP (10 per minute) and per email-IP pair (3 per minute) — exceeding either limit returns HTTP 429. Returns HTTP 204 on success.

@spec verify_magic_link(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AuthVerifyLink.AuthInput.t()
) :: {:ok, ArchAstro.Types.AuthTokens.t()} | {:error, ArchAstro.Error.reason()}

Verify a magic link token

Consumes a single-use token from a magic link URL and returns an access token, refresh token, and the authenticated user object. This endpoint completes both the login flow (initiated by /auth/request_login_link) and the registration flow (initiated by /auth/request_register_link or /auth/request_link).

Extract the token from the token query parameter of the magic link redirect URI and POST it here. Expired or already-used tokens return HTTP 401 — expired links carry the error code expired_token, unknown or already-used tokens carry invalid_or_expired_token. If the app has disabled passwordless authentication the request returns HTTP 403. Rate-limited to 10 requests per IP per minute — exceeding this returns HTTP 429.