> 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/api-specification/authentication.md).

# Authentication

## Authenticate user

> Authenticate a user using EIP712 signature or API key and return access/refresh tokens

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/auth/login":{"post":{"description":"Authenticate a user using EIP712 signature or API key and return access/refresh tokens","operationId":"AuthController_authenticate","parameters":[],"requestBody":{"required":true,"description":"Authentication request with EIP712 signature or API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticateRequestDto"}}}},"responses":{"200":{"description":"Authentication successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticateResponseDto"}}}},"400":{"description":"Bad request - invalid input data"},"401":{"description":"Unauthorized - authentication failed"}},"summary":"Authenticate user","tags":["Authentication"]}}},"components":{"schemas":{"AuthenticateRequestDto":{"type":"object","properties":{"method":{"type":"string","description":"Authentication method","enum":["eip712","api_key","privy_access_token"]},"address":{"type":"string","description":"User wallet address","pattern":"^0x[a-fA-F0-9]{40}$"},"clientId":{"type":"string","description":"Client identifier"},"details":{"description":"Authentication method specific details","oneOf":[{"$ref":"#/components/schemas/EIP712AuthDetailsDto"},{"$ref":"#/components/schemas/ApiKeyAuthDetailsDto"},{"$ref":"#/components/schemas/PrivyAuthDetailsDto"}]}},"required":["method","address","clientId","details"]},"EIP712AuthDetailsDto":{"type":"object","properties":{"signature":{"type":"string","description":"EIP712 signature"},"timestamp":{"type":"number","description":"Unix timestamp used in the signed message"},"chainId":{"type":"number","description":"EIP-155 chain ID used in the EIP712 domain when signing. Optional; falls back to server default (EIP712_CHAIN_ID) for backward compatibility."}},"required":["signature","timestamp"]},"ApiKeyAuthDetailsDto":{"type":"object","properties":{"apiKey":{"type":"string","description":"API key for authentication"}},"required":["apiKey"]},"PrivyAuthDetailsDto":{"type":"object","properties":{"appId":{"type":"string","description":"Privy App ID"},"accessToken":{"type":"string","description":"Privy access token (JWT)"}},"required":["appId","accessToken"]},"AuthenticateResponseDto":{"type":"object","properties":{"accessToken":{"type":"string","description":"JWT access token"},"refreshToken":{"type":"string","description":"Refresh token for obtaining new access tokens"},"tokenType":{"type":"string","description":"Token type"},"expiresIn":{"type":"number","description":"Token expiration time in seconds"},"address":{"type":"string","description":"User wallet address"},"clientId":{"type":"string","description":"Client identifier"}},"required":["accessToken","refreshToken","tokenType","expiresIn","address","clientId"]}}}}
```

## Get EIP712 message to sign

> Generate EIP712 structured data for client-side signing

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/auth/eip712-message":{"get":{"description":"Generate EIP712 structured data for client-side signing","operationId":"AuthController_getEIP712Message","parameters":[{"name":"address","required":true,"in":"query","description":"User wallet address","schema":{"type":"string"}},{"name":"clientId","required":true,"in":"query","description":"Client identifier","schema":{"type":"string"}},{"name":"chainId","required":true,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"EIP712 message generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetEIP712MessageResponseDto"}}}},"400":{"description":"Bad request - invalid parameters"}},"summary":"Get EIP712 message to sign","tags":["Authentication"]}}},"components":{"schemas":{"GetEIP712MessageResponseDto":{"type":"object","properties":{"domain":{"type":"object","description":"EIP712 domain"},"types":{"type":"object","description":"EIP712 types"},"primaryType":{"type":"string","description":"Primary type for EIP712 signing"},"message":{"type":"object","description":"Message to sign"},"timestamp":{"type":"number","description":"Unix timestamp used in message"}},"required":["domain","types","primaryType","message","timestamp"]}}}}
```

## Refresh access token

> Use a valid refresh token to obtain a new access token and refresh token

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/auth/refresh":{"post":{"description":"Use a valid refresh token to obtain a new access token and refresh token","operationId":"AuthController_refreshToken","parameters":[],"requestBody":{"required":true,"description":"Refresh token request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequestDto"}}}},"responses":{"200":{"description":"Token refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenResponseDto"}}}},"401":{"description":"Unauthorized - invalid or expired refresh token"}},"summary":"Refresh access token","tags":["Authentication"]}}},"components":{"schemas":{"RefreshTokenRequestDto":{"type":"object","properties":{"refreshToken":{"type":"string","description":"Refresh token"}},"required":["refreshToken"]},"RefreshTokenResponseDto":{"type":"object","properties":{"accessToken":{"type":"string","description":"New JWT access token"},"refreshToken":{"type":"string","description":"New refresh token"},"tokenType":{"type":"string","description":"Token type"},"expiresIn":{"type":"number","description":"Token expiration time in seconds"}},"required":["accessToken","refreshToken","tokenType","expiresIn"]}}}}
```

## Logout user

> Invalidate refresh token and log out the user

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/auth/logout":{"post":{"description":"Invalidate refresh token and log out the user","operationId":"AuthController_logout","parameters":[],"requestBody":{"required":true,"description":"Logout request with refresh token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoutRequestDto"}}}},"responses":{"200":{"description":"Logout successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoutResponseDto"}}}},"401":{"description":"Unauthorized - invalid refresh token"}},"summary":"Logout user","tags":["Authentication"]}}},"components":{"schemas":{"LogoutRequestDto":{"type":"object","properties":{"refreshToken":{"type":"string","description":"Refresh token to invalidate"}},"required":["refreshToken"]},"LogoutResponseDto":{"type":"object","properties":{"message":{"type":"string","description":"Logout status message"}},"required":["message"]}}}}
```