Tink.Auth (Tink v0.1.1)

Copy Markdown View Source

OAuth 2.0 authentication for Tink.

Supports all OAuth 2.0 grant types used by Tink API:

  • Client Credentials (service-to-service)
  • Authorization Code (user authorization)
  • Refresh Token

Examples

Client Credentials Flow

client = Tink.client()
{:ok, token_response} = Tink.Auth.get_access_token(client, "accounts:read")

Authorization Code Flow

# Step 1: Generate authorization URL
auth_url = Tink.Auth.authorization_url(
  client_id: "your_client_id",
  redirect_uri: "https://yourapp.com/callback",
  scope: "accounts:read,transactions:read",
  state: "random_state"
)

# Step 2: User visits URL and authorizes
# Step 3: Exchange code for token
{:ok, token_response} = Tink.Auth.exchange_code(client, code)

Refresh Token

{:ok, new_token} = Tink.Auth.refresh_access_token(client, refresh_token)

Summary

Functions

authorization_url(opts)

Generates an authorization URL for the authorization code flow.

create_authorization(client, params)

Creates an authorization grant for a user.

delegate_authorization(client, params)

Delegates authorization to another client (actor client).

exchange_code(client, code)

Exchanges an authorization code for an access token.

get_access_token(client, scope)

Gets an access token using client credentials grant.

refresh_access_token(client, refresh_token)

Refreshes an access token using a refresh token.

validate_token(client)

Validates an access token by making a lightweight API request.

Functions

authorization_url(opts)

@spec authorization_url(keyword()) :: String.t()

Generates an authorization URL for the authorization code flow.

Parameters

  • opts - Authorization options:
    • :client_id - OAuth client ID (required)
    • :redirect_uri - Callback URL (required)
    • :scope - OAuth scopes (required)
    • :state - CSRF protection state (recommended)
    • :market - Market code (optional)
    • :locale - Locale code (optional)

Examples

url = Tink.Auth.authorization_url(
  client_id: "your_client_id",
  redirect_uri: "https://yourapp.com/callback",
  scope: "accounts:read,transactions:read",
  state: SecureRandom.hex(32)
)

create_authorization(client, params)

@spec create_authorization(Tink.Client.t(), map()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Creates an authorization grant for a user.

Used in continuous access flow to create authorization codes for users.

Parameters

  • client - Tink client with authorization:grant access token
  • params - Authorization parameters:
    • :user_id - Tink user ID (required)
    • :scope - OAuth scopes (required)

Examples

{:ok, %{"code" => code}} = Tink.Auth.create_authorization(client, %{
  user_id: "user_abc",
  scope: "accounts:read,transactions:read"
})

delegate_authorization(client, params)

@spec delegate_authorization(Tink.Client.t(), map()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Delegates authorization to another client (actor client).

Used in Tink Link flows.

Parameters

  • client - Tink client with authorization:grant access token
  • params - Delegation parameters:
    • :user_id - Tink user ID (required)
    • :id_hint - Human-readable user identifier (required)
    • :scope - OAuth scopes (required)
    • :actor_client_id - Actor client ID (optional, defaults to client_id)

Examples

{:ok, %{"code" => code}} = Tink.Auth.delegate_authorization(client, %{
  user_id: "user_abc",
  id_hint: "john.doe@example.com",
  scope: "credentials:read,credentials:write"
})

exchange_code(client, code)

@spec exchange_code(Tink.Client.t(), String.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Exchanges an authorization code for an access token.

Parameters

  • client - Tink client
  • code - Authorization code from callback

Examples

{:ok, token_response} = Tink.Auth.exchange_code(client, code)

get_access_token(client, scope)

@spec get_access_token(Tink.Client.t(), String.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Gets an access token using client credentials grant.

Parameters

  • client - Tink client with client_id and client_secret
  • scope - OAuth scope string (required)

Examples

{:ok, %{"access_token" => token}} = Tink.Auth.get_access_token(client, "accounts:read")

refresh_access_token(client, refresh_token)

@spec refresh_access_token(Tink.Client.t(), String.t()) ::
  {:ok, map()} | {:error, Tink.Error.t()}

Refreshes an access token using a refresh token.

Parameters

  • client - Tink client
  • refresh_token - Refresh token from previous token response

Examples

{:ok, new_token} = Tink.Auth.refresh_access_token(client, refresh_token)

validate_token(client)

@spec validate_token(Tink.Client.t()) :: {:ok, boolean()}

Validates an access token by making a lightweight API request.

Examples

{:ok, true} = Tink.Auth.validate_token(client)
{:ok, false} = Tink.Auth.validate_token(invalid_client)