Unit.API.Tokens (Unit v1.0.0)

API module for Unit API Tokens (Org, Customer, Cardholder).

Token hierarchy

Org tokens — long-lived, server-side; never expose to clients
Customer tokens — scoped bearer tokens for front-end use (max 24 hours)
Cardholder tokens — single-card-scoped for sensitive card operations

Two-factor authentication

Some scopes require 2FA. First call create_customer_token_verification/3 to send an OTP to the customer's phone, then pass the received verification_token and the 6-digit verification_code to create_customer_token/3.

In sandbox, use passcode 000001.

Summary

Functions

create_cardholder_token(card_id, params, opts \\ [])

Create a cardholder bearer token for a specific card.

create_customer_token(customer_id, params, opts \\ [])

Create a customer bearer token.

create_customer_token_verification(customer_id, params \\ %{}, opts \\ [])

Create a customer token verification (sends OTP to customer's phone).

create_org_token(user_id, params, opts \\ [])

Create an org API token.

list_org_tokens(user_id, opts \\ [])

List all org tokens for a user.

revoke_org_token(user_id, token_id, opts \\ [])

Revoke an org token.

Functions

create_cardholder_token(card_id, params, opts \\ [])

@spec create_cardholder_token(String.t(), map(), keyword()) ::
  {:ok, Unit.Resource.Token.t()} | {:error, term()}

Create a cardholder bearer token for a specific card.

Params

:scope — e.g. "cards" (required)
:expires_in, :verification_token, :verification_code

create_customer_token(customer_id, params, opts \\ [])

@spec create_customer_token(String.t(), map(), keyword()) ::
  {:ok, Unit.Resource.Token.t()} | {:error, term()}

Create a customer bearer token.

Params

:scope — space-delimited scopes (e.g. "customers accounts transactions")
:expires_in — lifetime in seconds (max 86400)
:verification_token / :verification_code — required for 2FA scopes
:resources — restrict token to specific resource IDs

create_customer_token_verification(customer_id, params \\ %{}, opts \\ [])

@spec create_customer_token_verification(String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Create a customer token verification (sends OTP to customer's phone).

Returns a verificationToken to pass to create_customer_token/3.

Params

:channel — "sms" (default) or "call"
:phone — override phone number

create_org_token(user_id, params, opts \\ [])

@spec create_org_token(String.t(), map(), keyword()) ::
  {:ok, Unit.Resource.Token.t()} | {:error, term()}

Create an org API token.

list_org_tokens(user_id, opts \\ [])

@spec list_org_tokens(
  String.t(),
  keyword()
) :: {:ok, [Unit.Resource.Token.t()], map()} | {:error, term()}

List all org tokens for a user.

revoke_org_token(user_id, token_id, opts \\ [])

@spec revoke_org_token(String.t(), String.t(), keyword()) ::
  {:ok, nil} | {:error, term()}

Revoke an org token.