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

# Authentication Process

### Authentication

Pear Protocol uses EIP-712 wallet signature authentication combined with JWT tokens. No passwords required — wallet ownership is the identity.

#### Authentication Flow

```mermaid
sequenceDiagram
    participant User
    participant UserWallet as User's Wallet
    participant PearProtocol as Pear Protocol

    Note over User,PearProtocol: 1. EIP-712 authentication (one-time)
    User->>PearProtocol: Request EIP-712 message to sign
    PearProtocol-->>User: EIP-712 message
    User->>UserWallet: Sign EIP-712 message
    UserWallet-->>User: Signed message
    User->>PearProtocol: POST Authenticate API (signed message)
    PearProtocol-->>User: JWT tokens (access + refresh)

    Note over User,PearProtocol: 2. Generate API key
    User->>PearProtocol: POST /api-keys (name: "Trading Bot Key")
    PearProtocol-->>User: API key (store this securely)

    Note over User,PearProtocol: 3. Ongoing usage (no wallet needed)
    User->>PearProtocol: POST Authenticate API (method: "api_key", apiKey)
    PearProtocol-->>User: JWT tokens (access + refresh)
    User->>PearProtocol: API request with Authorization: Bearer <access_token>
    PearProtocol-->>User: API response
```

**Step 1: EIP-712 Authentication**

Request an EIP-712 message via `GET /auth/eip712-message` with your `address` and `clientId`, sign it with your wallet, then send the signature to `POST /auth/authenticate`:

```json
{
  "method": "eip712",
  "address": "0x1234...5678",
  "clientId": "YOUR_CLIENT_ID",
  "details": {
    "signature": "0xabcdef...",
    "timestamp": 1703872800
  }
}
```

On success, the server returns JWT tokens:

| Token         | Default Expiry |
| ------------- | -------------- |
| Access token  | 15 minutes     |
| Refresh token | 30 days        |

**Step 2: Generate API Key**

Using the access token from step 1, create an API key:

`POST /api-keys`

```json
{
  "name": "Trading Bot Key"
}
```

Response:

```json
{
  "id": "key-id",
  "apiKey": "your-api-key-value",
  "name": "Trading Bot Key",
  "createdAt": "2025-05-15T10:00:00.000Z"
}
```

**Store the `apiKey` value immediately** — it is only returned once at creation time.

**Step 3: Authenticate with API Key**

From now on, use the stored API key to get JWT tokens — no wallet interaction needed:

`POST /auth/authenticate`

```json
{
  "method": "api_key",
  "address": "0x1234...5678",
  "clientId": "YOUR_CLIENT_ID",
  "details": {
    "apiKey": "your-api-key-value"
  }
}
```

This returns JWT tokens. Use the access token in all requests:

```
Authorization: Bearer <access_token>
```

#### Client ID

`clientId` is required in all authentication requests (EIP-712 and API key).

* Individual traders: use `APITRADER`.
* Products built on top of the API: contact us to obtain your own Client ID. This lets us track usage and provide partner-specific features.

#### Refresh Token

When the access token expires, call `POST /auth/refresh` with the refresh token to get a new access token without signing again.

#### Logout

Call `POST /auth/logout` with the refresh token to invalidate the session server-side.