Fig Markets API Authentication Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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 API key's client identifier
• Client Secret: Your API key's client secret
• Token Endpoint: The OAuth2 token endpoint for the appropriate environment

Environment URLs

Authentication Flow

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

   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"

2. Response: You'll receive a JSON response containing:

   {
     "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
     "expires_in": 300,
     "token_type": "Bearer"
   }

   The client credentials grant does not return a refresh token; request a new access token with the same credentials instead. expires_in is the number of seconds until the access token expires. Read it from each response rather than assuming a fixed lifetime.

3. Use the Token: Send the access token in the Authorization header of every request, as Bearer <token> (the scheme is case-sensitive). Every REST request must also be signed with the X-FIG-Signature and X-FIG-Timestamp headers; see Signing Requests.

   curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "X-FIG-Signature: YOUR_SIGNATURE" \
     -H "X-FIG-Timestamp: YOUR_TIMESTAMP" \
     "https://api.test.figmarkets.com/v1/rfq"

4. Token Refresh: To avoid service interruptions, request a new access token before the current one expires, for example when about 20% of expires_in remains. Use the same client credentials request as in step 1.

WebSocket Authentication

A WebSocket connection must authenticate with an auth message within 30 seconds of opening, and must send a heartbeat message at least every 30 seconds from the moment it opens, including before and while it authenticates.

WebSocket messages are not signed: the request signature applies to REST requests only.

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

1. Using an access token obtained as described in REST API Authentication
2. Using your client credentials

WebSocket Connection URLs

Authentication Process

1. Connect to WebSocket: Establish a WebSocket connection to the appropriate server URL, and start sending heartbeats (step 4).

2. Send Authentication Message: Send a JSON-RPC authentication message with your access token or client credentials:

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

   OR

   {
     "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 responds with a new access token, which can also be used as the bearer token in REST API requests.

   If you use an existing token, the server validates it and responds with a success response.

3. Authentication Response: On success, the server responds with:

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

   On failure, the response carries a JSON-RPC error instead of a result:

   {
     "jsonrpc": "2.0",
     "id": "your_request_id",
     "error": {
       "code": -32001,
       "message": "Invalid token"
     }
   }

   The message is Invalid token, Invalid credentials or Authentication failed or required.

4. Session Maintenance: Send a heartbeat message at least every 30 seconds:

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

   The heartbeat responds with the time it was received, as a unix timestamp in milliseconds:

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

Token Refresh

WebSocket sessions are bound to the lifetime of the access token used during authentication. If your token expires, the session will be terminated. To maintain a long-lived WebSocket connection, you must refresh your token before it expires.

To refresh your token, first obtain a new access token using the client credentials flow (as described in the REST API section above), then send an auth/refresh message over the WebSocket:

{
  "jsonrpc": "2.0",
  "id": "your_request_id",
  "method": "auth/refresh",
  "params": {
    "token": "YOUR_NEW_ACCESS_TOKEN"
  }
}

The server will validate the new token, verify it belongs to the same user as the current session, and update the session expiry:

{
  "jsonrpc": "2.0",
  "id": "your_request_id",
  "method": "auth/refresh",
  "result": {
    "success": true
  }
}

It is recommended to refresh the token when about 20% of its lifetime remains.

Important Notes

• Token Expiration: WebSocket sessions are terminated when the access token expires. Use auth/refresh to extend the session before this happens.
• Heartbeat Requirement: The heartbeat clock starts when the connection opens; auth and subscribe do not reset it. A connection with no heartbeat for 45 seconds is closed with code 1008 (heartbeat not received).
• Reconnection: If your WebSocket connection is lost, you will need to re-authenticate and subscribe again.
• Authentication Timeout: A connection that has not authenticated within 30 seconds of opening is closed. If auth is refused, send auth again with a valid token or credentials: auth/refresh only extends a session that is already authenticated.
• Failed Attempts: After 3 refused auth or auth/refresh messages, the connection is closed with code 1008 (too many failed authentication attempts). Each IP address can send at most 120 auth and auth/refresh messages a minute.

Error Handling

REST authentication and signing errors return a JSON body with code and message:

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