Supabase.Auth.OAuth.Behaviour behaviour (supabase_auth v1.0.1)

@type authorization_details() :: %{
  authorization_id: String.t(),
  redirect_url: String.t() | nil,
  client: oauth_client(),
  user: %{id: String.t(), email: String.t()},
  scope: String.t()
}

Authorization request details for consent flow.

Fields

:authorization_id - Unique identifier for this authorization request
:redirect_url - If present, user has already consented and should be redirected (early-exit scenario)
:client - The OAuth client requesting authorization
:user - User information (id and email)
:scope - Space-separated string of requested scopes

consent_response()

@type consent_response() :: %{redirect_url: String.t()}

Response from consent approval or denial.

Fields

:redirect_url - URL to redirect the user to complete the OAuth flow

oauth_client()

@type oauth_client() :: %{
  id: String.t(),
  name: String.t(),
  uri: String.t(),
  logo_uri: String.t() | nil
}

OAuth client representation.

Fields

:id - Unique identifier for the OAuth client
:name - Human-readable name of the client application
:uri - Client application URI
:logo_uri - Optional URI to the client's logo

oauth_grant()

@type oauth_grant() :: %{
  client: oauth_client(),
  scopes: [String.t()],
  granted_at: String.t()
}

OAuth grant representing user authorization to a client.

Fields

:client - The OAuth client that was granted access
:scopes - List of scopes that were granted
:granted_at - ISO8601 timestamp when the grant was created

Callbacks

approve_authorization(client, session, authorization_id)

@callback approve_authorization(
  client :: Supabase.Client.t(),
  session :: Supabase.Auth.Session.t(),
  authorization_id :: String.t()
) :: {:ok, consent_response()} | {:error, term()}

Approves an OAuth authorization request.

Returns a redirect_url to continue the OAuth flow.

deny_authorization(client, session, authorization_id)

@callback deny_authorization(
  client :: Supabase.Client.t(),
  session :: Supabase.Auth.Session.t(),
  authorization_id :: String.t()
) :: {:ok, consent_response()} | {:error, term()}

Denies an OAuth authorization request.

Returns a redirect_url to inform the client of the denial.

get_authorization_details(client, session, authorization_id)

@callback get_authorization_details(
  client :: Supabase.Client.t(),
  session :: Supabase.Auth.Session.t(),
  authorization_id :: String.t()
) :: {:ok, authorization_details()} | {:error, term()}

Retrieves authorization details for a consent request.

Returns information about the OAuth client and requested scopes. If the user has already consented, includes a redirect_url for early-exit.

list_grants(client, session)

@callback list_grants(client :: Supabase.Client.t(), session :: Supabase.Auth.Session.t()) ::
  {:ok, [oauth_grant()]} | {:error, term()}

Lists all OAuth grants for the authenticated user.

Returns a list of all third-party applications that the user has authorized.

revoke_grant(client, session, client_id)

@callback revoke_grant(
  client :: Supabase.Client.t(),
  session :: Supabase.Auth.Session.t(),
  client_id :: String.t()
) :: :ok | {:error, term()}

Revokes an OAuth grant for a specific client.

Removes authorization for a third-party application.