> For the complete documentation index, see [llms.txt](https://pool-party-xyz.gitbook.io/pool-party-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pool-party-xyz.gitbook.io/pool-party-docs/core-api/authentication.md).

# 🔓 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.