> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pag.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Web3 challenge-response authentication endpoints: challenge, verification, and JWT token issuance.

Authentication follows the challenge-response model (SIWS style). The application requests a challenge, signs it with the user's wallet, and sends the signature to receive a JWT token.

<Info>
  The official SDK orchestrates the whole flow via `client.auth.signIn(...)`. See [Authentication and Configuration](/en/sdks/authentication).
</Info>

## Request challenge

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

<ParamField body="address" type="string" required>
  Wallet address that will authenticate.
</ParamField>

<ParamField body="blockchain" type="string" required>
  Blockchain of the address (for example, `solana`).
</ParamField>

<ResponseField name="challenge" type="string">
  Challenge message (nonce) to be signed by the wallet.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://app.pag.finance/api/auth/challenge \
    -H "Content-Type: application/json" \
    -d '{ "address": "7NaNvh...", "blockchain": "solana" }'
  ```

  ```ts SDK theme={null}
  const { challenge } = await client.auth.challenge({
    address,
    blockchain: 'solana',
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "challenge": "pag.finance quer que você assine: nonce=8f3c..."
    }
  }
  ```
</ResponseExample>

## Verify signature

Sends the challenge signature and receives the JWT token.

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

<ParamField body="address" type="string" required>
  Wallet address.
</ParamField>

<ParamField body="blockchain" type="string" required>
  Blockchain of the address.
</ParamField>

<ParamField body="signature" type="string" required>
  Challenge signature produced by the wallet.
</ParamField>

<ResponseField name="tokenJWT" type="string">
  JWT token to be used in the `Authorization` header of authenticated calls.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://app.pag.finance/api/auth/verify \
    -H "Content-Type: application/json" \
    -d '{ "address": "7NaNvh...", "blockchain": "solana", "signature": "..." }'
  ```

  ```ts SDK theme={null}
  const { tokenJWT } = await client.auth.signIn(
    { address, blockchain: 'solana' },
    (challenge) => wallet.signMessage(new TextEncoder().encode(challenge)),
  );
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "tokenJWT": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
    }
  }
  ```
</ResponseExample>

## Send OTP

Sends a one-time password (OTP) as an additional factor, when applicable to the flow.

<ResponseField name="sent" type="boolean">
  Indicates whether the code was sent successfully.
</ResponseField>

<RequestExample>
  ```ts SDK theme={null}
  await client.auth.otpSend({ /* OTP flow parameters */ });
  ```
</RequestExample>

## Token usage

Include the JWT token in the `Authorization` header of every authenticated call:

```http theme={null}
Authorization: Bearer <tokenJWT>
```

<Warning>
  On `401` responses, sign in again. The SDK can automate this process with `client.auth.enableAutoRelogin(...)`.
</Warning>