> ## Documentation Index
> Fetch the complete documentation index at: https://gnosispay-feat-changelog-feature.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication Flow

> Use Sign-In with Ethereum (SIWE) to authenticate API requests.

Our authentication system uses Sign-In with Ethereum (SIWE) to generate a `jwt` to interact with our API.
This means you don't need to handle the storage of a powerful API key or spend hours configuring granular permissions.

Our API accepts signatures from Externally Owned Accounts (EOAs) and Smart Accounts (EIP-1271).

<Warning>
  The signer must be an owner of a Gnosis Pay account.
  Non-registered users will receive `401 Unauthorized` on most authenticated routes
</Warning>

## Token Details

A `jwt` is generated upon successful Sign-In with Ethereum (SIWE) verification and remains **valid for 1 hour**.
To enhance security and prevent replay attacks, each authentication attempt requires a new and unique nonce.

Always ensure that the `jwt` is valid before making API requests.
If an API request returns a 401 Unauthorized response due to an expired token,
your application must restart the authentication process, which requires user interaction.
This means the application must request a new nonce, prompt the user to sign the message,
and then submit the signature for verification to generate a fresh `jwt`.

## Authentication Process

### 1. Nonce Generation

Before initiating authentication, the application must request a nonce.
Your application then presents this nonce to the user for signing as part of the SIWE flow.

<RequestExample>
  ```bash cURL
  curl -X GET /api/v1/auth/nonce
  ```
</RequestExample>

### 2. Signature Verification

<RequestExample>
  ```bash cURL
  curl -X POST /api/v1/auth/challenge \
    -H "Content-Type: application/json" \
    -d '{
      "message": "string",
      "signature": "string"
    }'
  ```
</RequestExample>

<Warning>
  The SIWE message contains a `domain` and a `uri` field. You should ensure their values are **not** `127.0.0.1` or `localhost`, even when working locally. Override these fields (e.g., with `domain: "somedomain.com", uri: "https://www.somedomain.com"`) to prevent firewall blocks and "WAFForbidden" errors.
</Warning>

Upon successful verification, a `jwt` is generated.
This `jwt` must be included in the Authorization header of all subsequent HTTP requests to authenticate with the Gnosis Pay API:

```bash
Authorization: Bearer {jwt}
```