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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pearprotocol.io/api-integration/access-management/authentication-process.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.