@spec authenticate(String.t(), options()) :: {:ok, auth_response()} | {:error, term()}

Convenience function to start authentication with BankID.

This function initiates an authentication order and returns the necessary tokens for QR code generation and polling.

Parameters

• end_user_ip - IP address of the end user (required)
• opts - Keyword list of optional parameters

Options

• :personal_number - Require authentication from specific user (format: YYYYMMDDXXXX)
• :user_visible_data - Custom message shown to user during authentication
• :user_visible_data_format - Format of the message (default: "simpleMarkdownV1")
• :user_non_visible_data - Data not shown to user but included in signature

Returns

• {:ok, auth_response} - Authentication was initiated successfully
• {:error, reason} - Authentication initiation failed

Errors

• :invalid_ip - Invalid IP address format
• :invalid_personal_number - Invalid personal number format
• :network_error - Connection to BankID failed
• :bankid_error - BankID API returned an error

Examples

# Simple authentication
{:ok, auth} = BankID.authenticate("192.168.1.1")

# With specific user
{:ok, auth} = BankID.authenticate("192.168.1.1", 
  personal_number: "199001011234")

# With custom message
{:ok, auth} = BankID.authenticate("192.168.1.1",
  user_visible_data: "Login to MyApp")

See BankID.Client.authenticate/2 for full documentation.

@spec cancel(String.t(), options()) :: :ok | {:error, term()}

Convenience function to cancel an authentication order.

Cancels an ongoing authentication order and releases any associated resources. Should be called when user cancels the authentication flow or when the session times out.

Parameters

• order_ref - The order reference from authentication response
• opts - Keyword list of options (currently unused)

Returns

• :ok - Authentication order was successfully cancelled
• {:error, reason} - Failed to cancel the authentication order

Errors

• :not_found - Order reference not found or already expired
• :already_cancelled - Order was already cancelled
• :network_error - Connection to BankID failed
• :bankid_error - BankID API returned an error

Examples

{:ok, auth} = BankID.authenticate("192.168.1.1")

# User cancelled - clean up the order
:ok = BankID.cancel(auth.order_ref)

# In Phoenix controller cleanup
def logout(conn, _params) do
  if order_ref = get_session(conn, :order_ref) do
    BankID.cancel(order_ref)
  end
  # ... rest of logout logic
end

See BankID.Client.cancel/2 for full documentation.

@spec collect(String.t(), options()) :: {:ok, collect_response()} | {:error, term()}

Convenience function to poll for authentication status.

Polls the BankID API to check the current status of an authentication order. Should be called every 2 seconds until authentication is complete or fails.

Parameters

• order_ref - The order reference from authentication response
• opts - Keyword list of options (currently unused)

Returns

• {:ok, collect_response} - Current status of authentication
• {:error, reason} - Failed to collect status

Status Values

• "pending" - Authentication is still in progress
• "complete" - Authentication succeeded
• "failed" - Authentication failed

Hint Codes (for pending status)

• "outstandingTransaction" - User needs to open BankID app
• "noClient" - Starting BankID app on user's device
• "started" - User has BankID app open
• "userSign" - User is confirming in the app

Hint Codes (for failed status)

• "userCancel" - User cancelled authentication
• "expiredTransaction" - Authentication session expired
• "certificateErr" - Certificate error
• "startFailed" - Failed to start BankID

Examples

{:ok, auth} = BankID.authenticate("192.168.1.1")

# Poll every 2 seconds
{:ok, result} = BankID.collect(auth.order_ref)

case result.status do
  "pending" -> # Continue polling
  "complete" -> # Authentication successful
  "failed" -> # Handle error based on result.hint_code
end

See BankID.Client.collect/2 for full documentation.

@spec extract_user_info(map()) :: user_info()

Extract user information from BankID completion data.

Parses the completion data returned by BankID after successful authentication and extracts the most commonly used user information in a convenient format.

Parameters

• completion_data - The completion data from a successful collect response

Returns

A map containing extracted user information with keys:

• :personal_number - Swedish personal identity number (YYYYMMDDXXXX)
• :given_name - First name of the authenticated user
• :surname - Last name of the authenticated user

Examples

{:ok, result} = BankID.collect(order_ref)
if result.status == "complete" do
  user_info = BankID.extract_user_info(result.completion_data)
  # %{
  #   personal_number: "199001011234",
  #   given_name: "Erik", 
  #   surname: "Andersson"
  # }

  # Store in database or create user session
  create_user_session(user_info)
end

Notes

This function extracts only the basic user information. If you need additional data like device information or signature details, access completion_data directly.

See BankID.Client.extract_user_info/1 for full documentation.