# Fig Markets API Authentication Guide

This guide explains how to authenticate with the Fig Markets API using the FIG identity platform.

## REST API Authentication

The Fig Markets API uses OAuth2/OpenID Connect for authentication. You'll need to obtain an access token using the client credentials grant flow.

### Prerequisites

- **Client ID**: Your application's client identifier
- **Client Secret**: Your application's client secret
- **Token Endpoint**: The OAuth2 token endpoint for the appropriate environment


### Environment URLs

| Environment | Token Endpoint |
|  --- | --- |
| Production | `https://id.figmarkets.com/realms/figmarkets-api/protocol/openid-connect/token` |
| Test | `https://id.test.figmarkets.com/realms/figmarkets-api/protocol/openid-connect/token` |


### Authentication Flow

1. **Request Access Token**: Send a POST request to the token endpoint with your client credentials:



```bash
curl -X POST "https://id.test.figmarkets.com/realms/figmarkets-api/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
```

1. **Response**: You'll receive a JSON response containing:



```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}
```

1. **Use the Token**: Include the access token in the Authorization header for all API requests:



```bash
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://api.test.figmarkets.com/v1/endpoint"
```

1. **Token Refresh**: When the access token expires, use the refresh token to obtain a new one:



```bash
curl -X POST "https://id.test.figmarkets.com/realms/figmarkets-api/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
```

## WebSocket Authentication

For the websocket connect you will first need to authenticate to start a valid session.  Once authenticated you will need to send a heartbeat message every 30 seconds to keep the session alive.

There are two ways to authenticate with the Fig Markets WebSocket server:

1. Using a JWT token
2. Using client credentials


### Using a JWT token

To use a JWT token, you must first authenticate using the REST API method described above to obtain an access token.

### WebSocket Connection URLs

| Environment | WebSocket URL |
|  --- | --- |
| Test | `wss://ws.test.figmarkets.com` |
| Production | `wss://ws.figmarkets.com` |


### Authentication Process

1. **Connect to WebSocket**: Establish a WebSocket connection to the appropriate server URL
2. **Send Authentication Message**: Send a JSON-RPC authentication message with your access token or client credentials:



```json
{
  "jsonrpc": "2.0",
  "id": "your_request_id",
  "method": "auth",
  "params": {
    "token": "YOUR_ACCESS_TOKEN"
  }
}
```

OR


```json
{
  "jsonrpc": "2.0",
  "id": "your_request_id",
  "method": "auth",
  "params": {
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }
}
```

If you use client credentials, the server will respond with a new access token which can be used as the bearer token in future REST API requests.

If you use an existing token the server will validate the token and return with a success response if authentication is successful.

1. **Authentication Response**: The server will respond with a success or error message



```json
{
  "jsonrpc": "2.0",
  "id": "your_request_id",
  "method": "auth",
  "result": {
    "success": true,
    "token": "new_access_token_if_provided"
  }
}
```

1. **Session Maintenance**: Send a heartbeat message every 30 seconds to keep your session alive:



```json
{
  "jsonrpc": "2.0",
  "id": "your_request_id",
  "method": "heartbeat"
}
```

The heartbeat will respond with a message containing the time, as a unix timestamp in milliseconds, that the heartbeat was received:


```json
{
  "jsonrpc": "2.0",
  "id": "your_request_id",
  "method": "heartbeat",
  "result": 1703123456789
}
```

### Important Notes

- **Token Expiration**: WebSocket sessions depend on valid access tokens. Ensure your token is refreshed before it expires.
- **Heartbeat Requirement**: Failure to send heartbeat messages within 30 seconds will result in session termination.
- **Reconnection**: If your WebSocket connection is lost, you'll need to re-authenticate.


## Error Handling

Common authentication errors include:

- **401 Unauthorized**: Invalid or expired access token
- **403 Forbidden**: Insufficient permissions for the requested resource
- **400 Bad Request**: Malformed authentication request


Always check the error response body for detailed information about authentication failures.