supabase.auth — io.github.supabase-community/auth 0.4.0

Authentication and user management against Supabase Auth.

Supports password, OAuth, OTP, SSO, ID-token, Web3 and anonymous sign-in, user retrieval and sign-up, the full session/identity lifecycle (verify-otp, refresh-session, update-user, resend, reset-password-for-email, exchange-code-for-session, reauthenticate, get-claims, identity linking) and server observability (get-server-health, get-server-settings).

See supabase.auth.admin for the service-role admin API.

Example

(require '[supabase.core.client :as client]
         '[supabase.auth :as auth])

(def c (client/make-client "https://abc.supabase.co" "anon-key"))

(auth/sign-up c {:email "[e-mail]" :password "secure-password"})
(auth/sign-in-with-password c {:email "[e-mail]" :password "secure-password"})

Each function returns {:status :body :headers} on success or an anomaly map on failure. See https://supabase.com/docs/reference/javascript/auth-api

ensure-valid-session clj

(ensure-valid-session client session)

(ensure-valid-session client session opts)

Validates session and refreshes it when needed, in one operation.

Returns a session map that is neither expired nor about to expire, or an anomaly: :cognitect.anomalies/incorrect when the session is missing its tokens, or the refresh call's anomaly when the refresh fails.

Options

• :within — seconds before expiry that trigger a refresh (default 300)

Example

(let [session (ensure-valid-session client session)]
  (if (error/anomaly? session)
    (redirect-to-login)
    (make-api-call session)))

exchange-code-for-session clj

(exchange-code-for-session client params)

Completes the PKCE flow by exchanging an authorization code for a session.

Parameters

• client — Supabase client
• params:
  • :auth-code — code returned to the redirect URL (required)
  • :code-verifier — the verifier generated when the flow started (required)

Example

(exchange-code-for-session client {:auth-code "abc" :code-verifier "xyz"})

get-claims clj

(get-claims client jwt)

Returns the verified claims of a Supabase JWT.

For asymmetric algorithms (RS256, ES256) the signature is verified locally against the project's published JWKS (fetched once and cached). For the symmetric HS256 algorithm — which cannot be verified without the server secret — this falls back to a get-user call so the server validates the token.

Returns {:claims {...} :header {...}} on success, or an anomaly on a malformed/invalid/expired token.

Example

(get-claims client "eyJhbG...")

get-server-health clj

(get-server-health client)

Returns the auth server health payload (GET /health).

Example

(get-server-health client)

get-server-settings clj

(get-server-settings client)

Returns the auth server's advertised settings/capabilities (GET /settings).

Example

(get-server-settings client)

get-user clj

(get-user client access-token)

Retrieves the user profile associated with access-token.

Returns {:status 200 :body {...}} with the user payload, or an anomaly map on failure (invalid client, expired token, etc.).

Example

(get-user client "eyJhbG...")

get-user-identities clj

(get-user-identities client access-token)

Returns the identities linked to the user identified by access-token.

On success returns {:status 200 :body [...identities...]}.

Example

(get-user-identities client "<access-token>")

link-identity clj

(link-identity client access-token credentials)

Begins linking an OAuth identity to the user identified by access-token. Returns a response whose body contains a :url the caller navigates the user-agent to in order to authorize the new identity.

Parameters

• client — Supabase client
• access-token — the user's access token
• credentials:
  • :provider — OAuth provider (required)
  • :options:
    • :redirect-to — URL to redirect after authorization
    • :scopes — vector of OAuth scopes
    • :query-params — additional query params

Example

(link-identity client "<access-token>" {:provider "github"})

needs-refresh? clj

(needs-refresh? session)

(needs-refresh? session {:keys [within] :or {within 300}})

True when session is expired or expires within :within seconds (default 300). A session without expiry information never needs refresh.

Example

(needs-refresh? session)
(needs-refresh? session {:within 60})

reauthenticate clj

(reauthenticate client access-token)

Sends a reauthentication nonce (OTP) to the user's email or phone. Used before a password change when secure password change is enabled. The nonce is then passed to update-user as :nonce.

Example

(reauthenticate client "<access-token>")

refresh-if-needed clj

(refresh-if-needed client session)

(refresh-if-needed client session opts)

Refreshes session when it is expired or about to expire, otherwise returns it unchanged. Useful for proactive refresh in request handlers.

Returns the (possibly new) session map, or an anomaly when the refresh call fails.

Options

• :within — seconds before expiry that trigger a refresh (default 300)
• :force — refresh regardless of expiry

Example

(refresh-if-needed client session)
(refresh-if-needed client session {:within 60})
(refresh-if-needed client session {:force true})

refresh-session clj

(refresh-session client refresh-token)

Exchanges a refresh token for a fresh session. The caller is responsible for storing the returned access + refresh tokens.

Example

(refresh-session client "<refresh-token>")

resend clj

(resend client params)

Resends a signup confirmation or OTP for an existing, unconfirmed sign-up or change request.

Parameters

• client — Supabase client
• params:
  • :type — "signup", "email_change", "sms", or "phone_change" (required)
  • :email / :phone — the destination (one required)
  • :options:
    • :email-redirect-to — URL to redirect after confirmation
    • :captcha-token — CAPTCHA challenge token

Example

(resend client {:type "signup" :email "[e-mail]"})

reset-password-for-email clj

(reset-password-for-email client email)

(reset-password-for-email client email options)

Sends a password-recovery email. Complete the reset by verifying the emailed link (type "recovery") and calling update-user with the new password.

Parameters

• client — Supabase client
• email — the account email (required)
• options (optional):
  • :redirect-to — URL the recovery link points to
  • :captcha-token — CAPTCHA challenge token

Example

(reset-password-for-email client "[e-mail]")
(reset-password-for-email client "[e-mail]" {:redirect-to "https://app/reset"})

sign-in-anonymously clj

(sign-in-anonymously client credentials)

Signs in a user anonymously. Anonymous users can later be converted to permanent users by linking an identity.

Parameters

• client — Supabase client
• credentials — optional:
  • :data — additional data attached to the user
  • :captcha-token — CAPTCHA challenge token

Example

(sign-in-anonymously client {})
(sign-in-anonymously client {:data {:locale "en-US"}})

sign-in-with-id-token clj

(sign-in-with-id-token client credentials)

Signs in with an ID token issued by an external provider.

Supported providers: "google", "apple", "azure", "facebook", "kakao".

Parameters

• client — Supabase client
• credentials:
  • :provider — provider name (required)
  • :token — OIDC ID token issued by the provider (required)
  • :access-token — optional, if the ID token contains an at_hash claim
  • :nonce — optional, if the ID token contains a nonce claim
  • :options — optional:
    • :captcha-token — CAPTCHA challenge token

Example

(sign-in-with-id-token client {:provider "google" :token "eyJ..."})

sign-in-with-oauth clj

(sign-in-with-oauth client credentials)

Builds the OAuth provider redirect URL. Does not issue an HTTP request — the caller navigates the user-agent to :url.

Supported providers include "github", "google", "apple", "azure", "discord", "facebook", "gitlab", "linkedin", "slack", "twitch", "twitter", and others.

Parameters

• client — Supabase client
• credentials:
  • :provider — OAuth provider (required)
  • :options — optional:
    • :redirect-to — URL to redirect after authentication
    • :scopes — vector of OAuth scopes
    • :query-params — additional query params for the OAuth URL
    • :skip-browser-redirect — skip browser redirect

Example

(sign-in-with-oauth client
  {:provider "github"
   :options {:redirect-to "https://example.com/callback"}})
;; => {:provider "github"
;;     :flow-type "implicit"
;;     :url "https://abc.supabase.co/auth/v1/authorize?provider=github&redirect_to=..."}

sign-in-with-otp clj

(sign-in-with-otp client credentials)

Sends a one-time password to the user's email or phone.

The user completes sign-in by calling verify-otp with the code.

Parameters

• client — Supabase client
• credentials:
  • :email — user's email (required if :phone not provided)
  • :phone — user's phone (required if :email not provided)
  • :options — optional:
    • :data — additional data
    • :email-redirect-to — URL to redirect after email verification
    • :captcha-token — CAPTCHA challenge token
    • :channel — "sms" or "whatsapp" for phone OTPs
    • :should-create-user — create the user if they don't exist

Example

(sign-in-with-otp client {:email "[e-mail]"})
(sign-in-with-otp client {:phone "[phone]"
                           :options {:channel "sms"}})

sign-in-with-password clj

(sign-in-with-password client credentials)

Authenticates a user with email/phone and password.

Parameters

• client — Supabase client
• credentials:
  • :email — user's email (required if :phone not provided)
  • :phone — user's phone (required if :email not provided)
  • :password — user's password (required)
  • :options — optional:
    • :captcha-token — CAPTCHA challenge token
    • :data — additional data

Example

(sign-in-with-password client {:email "[e-mail]" :password "secure-password"})

sign-in-with-sso clj

(sign-in-with-sso client credentials)

Initiates SAML single sign-on. Returns a response whose body contains the SSO redirect URL.

Parameters

• client — Supabase client
• credentials:
  • :provider-id — SSO provider ID (required if :domain not provided)
  • :domain — SSO provider domain (required if :provider-id not provided)
  • :options — optional:
    • :redirect-to — URL to redirect after authentication
    • :captcha-token — CAPTCHA challenge token

Example

(sign-in-with-sso client {:domain "example.org"})
(sign-in-with-sso client {:provider-id "sso-provider-id"})

sign-in-with-web3 clj

(sign-in-with-web3 client credentials)

Signs in with a Web3 wallet (Ethereum or Solana).

The message must be signed client-side; Supabase Auth verifies the signature.

Parameters

• client — Supabase client
• credentials:
  • :chain — "ethereum" or "solana" (required)
  • :message — SIWE/SIWS message that was signed (required)
  • :signature — wallet signature of the message (required)
  • :options — optional:
    • :captcha-token — CAPTCHA challenge token

Example

(sign-in-with-web3 client {:chain "ethereum"
                            :message "example.com wants you to sign in..."
                            :signature "0xabc..."})

sign-up clj

(sign-up client credentials)

Creates a new user with email/phone and password.

Parameters

• client — Supabase client
• credentials — sign-up details:
  • :email — user's email address (required if :phone not provided)
  • :phone — user's phone number (required if :email not provided)
  • :password — user's password (required)
  • :options — optional:
    • :email-redirect-to — URL to redirect after email confirmation
    • :data — additional data attached to the user
    • :captcha-token — verification token from CAPTCHA challenge

Example

(sign-up client {:email "[e-mail]" :password "secure-password"})

unlink-identity clj

(unlink-identity client access-token identity-id)

Unlinks the identity identity-id from the user identified by access-token.

Example

(unlink-identity client "<access-token>" "<identity-id>")

update-user clj

(update-user client access-token attrs)

Updates attributes of the user identified by access-token.

Parameters

• client — Supabase client
• access-token — the user's access token
• attrs — at least one of:
  • :email — new email address
  • :phone — new phone number
  • :password — new password
  • :nonce — reauthentication nonce (for password change after reauthenticate)
  • :data — user metadata map

Example

(update-user client "<access-token>" {:password "new-secret"})

verify-otp clj

(verify-otp client params)

Verifies an OTP / magic-link token, completing the round-trip started by sign-in-with-otp, sign-up, resend, or reset-password-for-email.

Returns {:status 200 :body {...session...}} on success.

Parameters

• client — Supabase client
• params:
  • :type — one of "sms", "phone_change", "signup", "invite", "magiclink", "recovery", "email_change", "email", "phone" (required)
  • :token — the OTP code (required unless :token-hash is given)
  • :email / :phone — the address the OTP was sent to (required with :token)
  • :token-hash — hash from an email link (alternative to :token + email/phone)
  • :options:
    • :redirect-to — URL to redirect after verification
    • :captcha-token — CAPTCHA challenge token

Example

(verify-otp client {:type "email" :email "[e-mail]" :token "123456"})
(verify-otp client {:type "email" :token-hash "abc..."})