# `TruelayerClient.Auth`
[🔗](https://github.com/iamkanishka/truelayer_client/blob/v1.0.0/lib/truelayer_client/auth.ex#L1)

TrueLayer Authentication Server client.

Manages the full OAuth2 token lifecycle for both the Payments and Data APIs.

## Token isolation

Payments tokens (`:payments`) and Data tokens (`:data`) are stored in separate
slots in the token store. Each domain client requests the correct token type,
ensuring a Data token is never used to authorise a payment.

## Automatic refresh

`valid_token/2` automatically refreshes an expired token if a `:refresh_token`
is available. For client-credentials flows (`client_credentials/3`), the SDK
fetches a new token whenever the cached one has expired.

## Scopes

  * Payments scopes: `["payments"]`
  * Data scopes: `["accounts", "balance", "transactions", "cards", "info", "offline_access"]`

# `auth_link_option`

```elixir
@type auth_link_option() ::
  {:scopes, [String.t()]}
  | {:state, String.t()}
  | {:nonce, String.t()}
  | {:providers, [String.t()]}
  | {:enable_mock, boolean()}
```

# `auth_link`

```elixir
@spec auth_link(TruelayerClient.t(), [auth_link_option()]) ::
  {:ok, String.t()} | {:error, TruelayerClient.Error.t()}
```

Generate an OAuth2 authorization URL to redirect the user to for bank login.

## Options

  * `:scopes` - list of OAuth2 scopes (required)
  * `:state` - CSRF token (required — validate on redirect!)
  * `:nonce` - replay-protection nonce
  * `:providers` - whitelist of provider IDs shown to the user
  * `:enable_mock` - show the TrueLayer mock bank in Sandbox

## Example

    {:ok, url} = TruelayerClient.Auth.auth_link(client,
      scopes: TruelayerClient.Auth.payments_scopes(),
      state: csrf_token
    )
    # Redirect user to url

# `client_credentials`

```elixir
@spec client_credentials(
  TruelayerClient.t(),
  [String.t()],
  TruelayerClient.Auth.Token.token_type()
) ::
  {:ok, TruelayerClient.Auth.Token.t()} | {:error, TruelayerClient.Error.t()}
```

Obtain a client-credentials token (server-to-server, no user interaction).

Results are cached in the token store. The cache is checked first; a new
token is fetched only when the cached one has expired.

This is the primary token source for Payments, Payouts, and Mandates clients.

## Example

    {:ok, token} = TruelayerClient.Auth.client_credentials(
      client,
      TruelayerClient.Auth.payments_scopes(),
      :payments
    )

# `data_scopes`

```elixir
@spec data_scopes() :: [String.t()]
```

Default scopes for Data API user-delegated calls.

# `delete_credential`

```elixir
@spec delete_credential(TruelayerClient.t(), String.t()) ::
  :ok | {:error, TruelayerClient.Error.t()}
```

Delete a stored credential (DELETE /connect/token/{credentials_id}).

Requires a valid Data-scoped token.

# `exchange_code`

```elixir
@spec exchange_code(
  TruelayerClient.t(),
  String.t(),
  TruelayerClient.Auth.Token.token_type()
) ::
  {:ok, TruelayerClient.Auth.Token.t()} | {:error, TruelayerClient.Error.t()}
```

Exchange an authorization code for an access token (POST /connect/token).

Call this in your OAuth2 redirect handler with the `code` from query params.
The token is cached automatically in the configured store.

## Example

    def callback(conn, %{"code" => code, "state" => state}) do
      verify_csrf!(state)
      {:ok, token} = TruelayerClient.Auth.exchange_code(client, code, :payments)
      # Store token association with user session
    end

# `payments_scopes`

```elixir
@spec payments_scopes() :: [String.t()]
```

Default scopes for Payments API client-credentials calls.

# `refresh_token`

```elixir
@spec refresh_token(
  TruelayerClient.t(),
  String.t(),
  TruelayerClient.Auth.Token.token_type()
) ::
  {:ok, TruelayerClient.Auth.Token.t()} | {:error, TruelayerClient.Error.t()}
```

Refresh an access token using the stored refresh token.

Called automatically by `valid_token/2` when the cached token is expired
and has a refresh token available.

# `valid_token`

```elixir
@spec valid_token(TruelayerClient.t(), TruelayerClient.Auth.Token.token_type()) ::
  {:ok, TruelayerClient.Auth.Token.t()} | {:error, TruelayerClient.Error.t()}
```

Return a valid, non-expired token for `token_type`.

If the stored token is expired and a refresh token is available, it is
refreshed automatically. If no token is stored, returns `{:error, ...}`.

Used by Data API domain clients before each API call.

---

*Consult [api-reference.md](api-reference.md) for complete listing*