Skip to main content
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.

​
Authentication Process

1

Generate a Nonce to sign a SIWE Message

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.
cURL
curl -X GET /api/v1/auth/nonce
2

Sign the SIWE Message with your Wallet or Provider

Our API accepts signatures from Externally Owned Accounts (EOAs) and Smart Accounts (EIP-1271).
The signer must be an owner of a Gnosis Pay account. Non-registered users will receive 401 Unauthorized on most authenticated routes
3

Verify the Signature and get an Access Token

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
After the message is signed, you need to submit both the message and the signature to retrieve an Access Token:
cURL
curl -X POST /api/v1/auth/challenge \
  -H "Content-Type: application/json" \
  -d '{
    "message": "string",
    "signature": "string",
    "ttlInSeconds": 36000
  }'
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.
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: 
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.
⌘I