> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnosispay.com/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.

<Info>
  **For Partners**: If you're building a partner integration, make sure to register your domains through the [Partners Dashboard](https://partners.gnosispay.com/) during signup. This ensures your domains are whitelisted for SIWE authentication and prevents authentication failures.
</Info>

## Authentication Process

<Steps titleSize="h3">
  <Step title="Generate a Nonce to sign a SIWE Message">
    Before initiating authentication, [the application must request a nonce](/api-reference/authentication/generate-nonce).
    Your application then presents this nonce to the user for signing as part of the SIWE flow.

    ```bash cURL theme={null}
    curl -X GET /api/v1/auth/nonce
    ```
  </Step>

  <Step title="Sign the SIWE Message with your Wallet or Provider">
    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>
  </Step>

  <Step title="Verify the Signature and get an Access Token">
    <Note>
      **JWT length validity**

      * **Default Validity**: JWT tokens are valid for the duration specified in `ttlInSeconds` during SIWE authentication
      * **Minimum Duration**: 1 hour
      * **Maximum Duration**: 24 hours
    </Note>

    After the message is signed, you need to submit both the message and the signature to [retrieve an Access Token](/api-reference/authentication/verify-siwe-signature):

    ```bash cURL theme={null}
    curl -X POST /api/v1/auth/challenge \
      -H "Content-Type: application/json" \
      -d '{
        "message": "string",
        "signature": "string",
        "ttlInSeconds": 36000
      }'
    ```
  </Step>
</Steps>

<Warning>
  **Domain Whitelisting**: Gnosis Pay validates SIWE domains against a whitelist for security.

  * **localhost**: `localhost` (with or without ports like `localhost:3000`) is automatically allowed for local development
  * **Production domains**: All production and staging domains must be registered through the [Partners Dashboard](https://partners.gnosispay.com/) during signup
  * **127.0.0.1**: Avoid using `127.0.0.1` in SIWE messages as it may cause firewall blocks and "WAFForbidden" errors

  Only whitelisted domains (plus localhost) will be accepted for SIWE authentication.
</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 theme={null}
Authorization: Bearer {jwt}
```

## Details about the Access Token

A `jwt` is generated upon successful Sign-In with Ethereum (SIWE) verification and can remain valid for up to **24 hours**, depending on the **`ttlInSeconds`** parameter passed to SIWE, with a minimum validity period of 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`.