🔓 Authentication

🔑 API Key

📌 What is an API Key?

To ensure fair use and security, most endpoints require an x-api-key to be passed in the request headers. You can obtain an API Key by contacting the Pool Party team.

📥 How to Use

Include your API Key in every request like so:

POST /api/v1/auth/nonce HTTP/1.1
x-api-key: your-api-key-here

⚠️ Important: Keep your API Key secure. Do not expose it in client-side code or public repositories.

👤 Portfolio Endpoint

🔐 Authentication with accessToken

Access to a user's portfolio data requires both an x-api-key and a valid accessToken. The accessToken is obtained after the user authenticates with their wallet (e.g., MetaMask).

The authentication flow is wallet-based: the user signs a message with their wallet (e.g., MetaMask), and in return, they receive two tokens:

• accessToken: Used to authenticate API requests.

  • Expires in: 15 minutes

  • Usage: Sent in the Authorization header as a Bearer token.

• refreshToken: Used to obtain a new accessToken without requiring the user to sign in again.

  • Expires in: 7 days

  • Storage: Securely stored in an HttpOnly cookie on the client to prevent access via JavaScript (XSS protection).

🔐 Security Tip: Since the refresh token is stored in cookies with the HttpOnly and Secure flags, it cannot be accessed via client-side JavaScript, offering protection against most XSS attacks.

📥 How to Use

Include your accessToken in every request related to Portfolio like so:

GET /api/v1/portfolio?network=arbitrum HTTP/1.1
x-api-key: your-api-key-here
Authorization: Bearer {{accessToken}}

🔁 Token Refresh Flow

When the accessToken expires:

1. The client detects a 401 Unauthorized response.

2. A background request is automatically sent to /api/v1/auth/refresh.

3. The server uses the refreshToken stored in cookies to issue a new accessToken.

4. The client retries the original request with the new token.

🛡️ Security Notes

• The accessToken must be kept secure and is tied to the wallet signature.

• Tokens expire after a set period (e.g., 15m and 7 days) and must be refreshed using the refresh endpoint.

• Always validate the token on the backend.