WorkOS.AuthKit (WorkOS SDK for Elixir v3.0.1)

Copy Markdown View Source

Higher-level AuthKit authentication flow helpers.

Layered on top of WorkOS.UserManagement:

Summary

Types

pkce_authorization_url()

Result of get_pkce_authorization_url/2.

Functions

get_authorization_url(client, params \\ %{})

Builds an AuthKit authorization URL. See WorkOS.UserManagement.get_authorization_url/2 for the supported params.

get_pkce_authorization_url(client, params \\ %{})

Builds an AuthKit authorization URL with automatically generated PKCE parameters, plus a random state unless one is passed in params.

pkce_code_exchange(client, params, opts \\ [])

Exchanges an authorization code using a PKCE code verifier (public-client flow).

poll_device_code(client, device_code, opts \\ [])

Polls the authenticate endpoint until the user completes device authorization.

start_device_authorization(client, params \\ %{}, opts \\ [])

Initiates a device authorization flow, returning the device/user codes and verification URIs.

Types

pkce_authorization_url()

@type pkce_authorization_url() :: %{
  url: String.t(),
  code_verifier: String.t(),
  state: String.t()
}

Result of get_pkce_authorization_url/2.

Functions

get_authorization_url(client, params \\ %{})

@spec get_authorization_url(WorkOS.Client.t(), map()) :: String.t()

Builds an AuthKit authorization URL. See WorkOS.UserManagement.get_authorization_url/2 for the supported params.

get_pkce_authorization_url(client, params \\ %{})

@spec get_pkce_authorization_url(WorkOS.Client.t(), map()) :: pkce_authorization_url()

Builds an AuthKit authorization URL with automatically generated PKCE parameters, plus a random state unless one is passed in params.

Store code_verifier securely — it is required for the token exchange.

pkce_code_exchange(client, params, opts \\ [])

@spec pkce_code_exchange(WorkOS.Client.t(), map(), keyword()) ::
  {:ok, WorkOS.AuthenticateResponse.t()} | {:error, WorkOS.Error.error()}

Exchanges an authorization code using a PKCE code verifier (public-client flow).

Parameters

  • params — map with :code and :code_verifier

poll_device_code(client, device_code, opts \\ [])

@spec poll_device_code(WorkOS.Client.t(), String.t(), keyword()) ::
  {:ok, WorkOS.AuthenticateResponse.t()} | {:error, WorkOS.Error.error()}

Polls the authenticate endpoint until the user completes device authorization.

Waits :interval seconds (default 5, as recommended by the device authorization response) between attempts while the API reports authorization_pending. Options:

  • :interval — seconds between polls
  • :max_attempts — give up after this many polls (default :infinity), returning the last authorization_pending error

start_device_authorization(client, params \\ %{}, opts \\ [])

@spec start_device_authorization(WorkOS.Client.t(), map(), keyword()) ::
  {:ok, WorkOS.DeviceAuthorizationResponse.t()} | {:error, WorkOS.Error.error()}

Initiates a device authorization flow, returning the device/user codes and verification URIs.