Link an identity to a user
Link an OAuth identity to the current user.
Attach an additional OAuth identity (Google, GitHub, ...) to the currently signed-in user. Returns the URL the browser should be redirected to in order to authorize with the provider; on callback, the new identity is appended to the user's identities list.
A session is required — link_identity raises Supabase::Auth::Errors::AuthSessionMissing if no user is signed in.
Signature
supabase.auth.link_identity(credentials)credentials is a hash. Same shape as sign_in_with_oauth — provider: plus an optional options: hash.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | String | Required | OAuth provider name to link (e.g. google, github, gitlab, azure). |
options | Hash | Optional | Nested options: redirect_to (String, absolute callback URL), scopes (String, space-separated OAuth scopes), query_params (Hash, extra query parameters merged into the authorize URL). |
Returns
A Struct with :provider and :url. Redirect the browser to response.url; on successful provider callback the identity is linked to the current user.
Raises Supabase::Auth::Errors::AuthSessionMissing if there is no active session.
Example — link a GitHub identity
response = supabase.auth.link_identity(
provider: "github",
options: { redirect_to: "https://app.example.com/auth/callback" }
)
response.provider # => "github"
response.url # => "https://<project>.supabase.co/auth/v1/user/identities/authorize?..."
# In a Rails controller:
# redirect_to response.url, allow_other_host: trueExample — request extra scopes
response = supabase.auth.link_identity(
provider: "google",
options: {
scopes: "openid profile email https://www.googleapis.com/auth/calendar.readonly",
redirect_to: "https://app.example.com/auth/callback"
}
)Under flow_type: "pkce", the generated code verifier is stored for later consumption by exchange_code_for_session.