# `Tink.Auth`
[🔗](https://github.com/iamkanishka/tink.ex/blob/v0.1.1/lib/tink/auth.ex#L1)

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)

# `authorization_url`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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)

---

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