Supabase.Auth.Session (supabase_auth v0.10.0)

View Source

Represents an authenticated session with Supabase's Auth service.

A session contains the tokens and metadata necessary for authenticating subsequent API requests. It is returned after a successful sign-in or sign-up operation and can be refreshed using Supabase.Auth.refresh_session/2.

Fields

  • access_token - JWT token used for API authorization (required)
  • refresh_token - Token used to obtain a new access token when it expires (required)
  • expires_in - Number of seconds until the access token expires (required)
  • expires_at - Unix timestamp (in seconds) when the token expires
  • token_type - Type of token, usually "bearer" (required)
  • provider_token - OAuth provider-specific token (if applicable)
  • provider_refresh_token - OAuth provider-specific refresh token (if applicable)
  • user - The authenticated user's profile information (Supabase.Auth.User)

Usage

# Store the session securely after sign-in
{:ok, session} = Supabase.Auth.sign_in_with_password(client, credentials)

# Use the session for authenticated requests
{:ok, user} = Supabase.Auth.get_user(client, session)

# Refresh the session before it expires
{:ok, refreshed_session} = Supabase.Auth.refresh_session(client, session.refresh_token)

Security Notes

  • The access_token contains sensitive information and should be secured appropriately
  • Sessions should be refreshed before they expire to maintain authentication
  • For web applications, it's recommended to store session tokens in HTTP-only cookies

Summary

Types

t()

Functions

expired?(session)

Checks if the session token is expired.

expired_at?(expires_at)

Checks if a timestamp is expired.

expiring_soon?(session, opts \\ [])

Checks if the session token is expiring soon (within margin).

needs_refresh?(session, opts \\ [])

Checks if session needs refresh (expiring soon or expired).

parse(attrs)
seconds_until_expiry(session)

Returns seconds until token expiry.

valid?(session)

Checks if session has all required fields and is not expired.

Types

t()

@type t() :: %Supabase.Auth.Session{
  access_token: String.t(),
  expires_at: integer() | nil,
  expires_in: integer(),
  provider_refresh_token: String.t() | nil,
  provider_token: String.t() | nil,
  refresh_token: String.t(),
  token_type: String.t(),
  user: Supabase.Auth.User.t()
}

Functions

expired?(session)

@spec expired?(t()) :: boolean()

Checks if the session token is expired.

Examples

iex> expired?(session)
false

iex> expired?(%Session{expires_at: System.os_time(:second) - 100})
true

expired_at?(expires_at)

@spec expired_at?(integer() | nil) :: boolean()

Checks if a timestamp is expired.

Helper function for validating expiry times without requiring a full Session struct.

Examples

iex> expired_at?(System.os_time(:second) - 100)
true

iex> expired_at?(System.os_time(:second) + 100)
false

iex> expired_at?(nil)
false

expiring_soon?(session, opts \\ [])

@spec expiring_soon?(
  t(),
  keyword()
) :: boolean()

Checks if the session token is expiring soon (within margin).

Options

  • :within - Seconds before expiry to consider "expiring soon" (default: 300)

Examples

# With default 5-minute margin
iex> expiring_soon?(session)
false

# Custom margin
iex> expiring_soon?(session, within: 60)
true

# Session expires in 2 minutes, check with 5-minute margin
iex> session = %Session{expires_at: System.os_time(:second) + 120}
iex> expiring_soon?(session, within: 300)
true

needs_refresh?(session, opts \\ [])

@spec needs_refresh?(
  t(),
  keyword()
) :: boolean()

Checks if session needs refresh (expiring soon or expired).

Useful for determining when to proactively refresh tokens.

Options

  • :within - Seconds before expiry to consider needing refresh (default: 300)

Examples

iex> needs_refresh?(session)
false

iex> needs_refresh?(session, within: 60)
true

parse(attrs)

@spec parse(map()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}

seconds_until_expiry(session)

@spec seconds_until_expiry(t()) :: non_neg_integer() | nil

Returns seconds until token expiry.

Returns nil if expires_at is not set, or 0 if already expired.

Examples

iex> seconds_until_expiry(session)
3542

iex> seconds_until_expiry(%Session{expires_at: nil})
nil

valid?(session)

@spec valid?(t()) :: boolean()

Checks if session has all required fields and is not expired.

Examples

iex> valid?(%Session{access_token: "...", refresh_token: "...", expires_at: future})
true

iex> valid?(%Session{access_token: nil})
false