Set the session data

Restore an existing session by handing the client a previously-issued access_token and refresh_token — for example, tokens read from your own session storage when bootstrapping a new client instance. If the access token is still valid, set_session calls get_user to verify it and builds a fresh Session struct; if it's already expired, it falls back to a refresh-token exchange.

On success the new session is persisted to storage and a TOKEN_REFRESHED event is dispatched to on_auth_state_change subscribers.

Signature

supabase.auth.set_session(access_token, refresh_token)

Both arguments are positional and required.

Parameters

Name	Type	Required	Description
`access_token`	String	Required	JWT access token. Must have three dot-separated segments; otherwise treated as expired and a refresh is attempted.
`refresh_token`	String	Required	Refresh token paired with the access token. Used if the access token is expired; raises AuthSessionMissing when missing/empty in that branch.

Returns

Supabase::Auth::Types::AuthResponse

A Struct with :user and :session. When the access token was still valid, session carries the supplied tokens plus the freshly-fetched user. When the access token was expired, session holds the refreshed pair returned by GoTrue. Raises Supabase::Auth::Errors::AuthSessionMissing if the access token is expired and no usable refresh token was supplied, and Supabase::Auth::Errors::UserDoesntExist if the access token can't be matched to a user.

Example — restore a session from your own storage

tokens = MySessionStore.fetch(user_id)

response = supabase.auth.set_session(tokens[:access_token], tokens[:refresh_token])
response.session.user.email   # => "ada@example.com"

Example — fall back to refresh when the access token is expired

# access_token is past its exp; set_session refreshes transparently:
response = supabase.auth.set_session(expired_access_token, valid_refresh_token)

response.session.access_token   # => newly-rotated token
response.session.refresh_token  # => newly-rotated refresh token

Example — handle missing refresh token

begin
  supabase.auth.set_session(expired_access_token, "")
rescue Supabase::Auth::Errors::AuthSessionMissing
  # Token expired and no refresh token to recover with — sign the user in again.
end

`set_auth` vs `set_session`

This page covers auth.set_session. The top-level Supabase::Client#set_auth(token) is a separate method — use it when you already have a JWT and want to swap the Authorization header on every sub-client without touching session state. Use set_session when you also have the matching refresh token and want full session management (storage, auto-refresh, state-change events).