Retrieve a new session

Rotate the current session's tokens by sending its refresh token to GoTrue's POST /token?grant_type=refresh_token. Unlike get_session, which only refreshes when within ten seconds of expiry, refresh_session always hits the endpoint.

If no refresh_token argument is provided, the current session's refresh token is used. A SIGNED_IN → TOKEN_REFRESHED event is dispatched to on_auth_state_change subscribers, and the new session replaces the persisted one.

Signature

supabase.auth.refresh_session(refresh_token = nil)

refresh_token is an optional positional argument — pass it to refresh a session held outside the client. When omitted, the current session's refresh token is used.

Parameters

Name	Type	Required	Description
`refresh_token`	String	Optional	Optional refresh token. If nil, the current session's refresh token is used. Raises AuthSessionMissing if neither is available.

Returns

Supabase::Auth::Types::AuthResponse

A Struct with :user and :session (access_token, refresh_token, expires_at, user). The returned session is also persisted to storage and stored as the current session. Raises Supabase::Auth::Errors::AuthSessionMissing if no refresh token is supplied and no current session exists, or if the refresh attempt comes back without a session.

Example — refresh the current session

response = supabase.auth.refresh_session

response.session.access_token  # => "eyJhbGciOi..."  (newly rotated)
response.session.expires_at    # => 1717968000        (newer expiry)

Example — refresh a session stored elsewhere

# Pull a refresh token out of your own session storage:
stored_refresh_token = MySessionStore.fetch(user_id)

response = supabase.auth.refresh_session(stored_refresh_token)
MySessionStore.save(user_id, response.session)

Example — handle a missing session

begin
  supabase.auth.refresh_session
rescue Supabase::Auth::Errors::AuthSessionMissing
  # No active session — redirect to /sign-in
end

Dispatches TOKEN_REFRESHED via _notify_all_subscribers so anyone subscribed through on_auth_state_change sees the new session in real time.