Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Server-to-Server (S2S) authentication enables your backend services to make authenticated API requests to Firmly APIs. This method is designed for backend integrations where your server communicates directly with Firmly’s APIs.

​
Required Headers

​
x-firmly-authorization
string
required
Server-to-server secret token provisioned by Firmly. This is not your APPID — it is a dedicated secret mapped internally to your tenant for request isolation.
​
x-firmly-device-id
string
required
The device identifier of the client making the request. Your backend passes this through when making API calls on behalf of a client device.

​
Device ID

The x-firmly-device-id is used for cart isolation and session management. Pass through your client’s device ID when making API calls on their behalf.

​
Device ID Requirements

RuleRequirement
PresenceMust be present and non-empty
Max Length256 characters
Allowed Charactersa-z, A-Z, 0-9, -, _
Valid Examples:
  • user-12345
  • session_abc123
  • 82b10522-5483-4719-b599-6d78b12827f0
Invalid Examples:
  • Empty string
  • user.id (period not allowed)
  • user id (space not allowed)

​
Code Examples

curl -X POST https://api.firmly.work/api/v1/discovery/search \
  -H "x-firmly-authorization: YOUR_S2S_SECRET" \
  -H "x-firmly-device-id: user-12345" \
  -H "Content-Type: application/json" \
  -d '{"query": "running shoes"}'

​
Error Responses

The x-firmly-device-id header is missing or empty.
{
  "error": "BadRequest",
  "message": "Missing x-firmly-device-id header"
}
The device ID exceeds 256 characters or contains invalid characters.
{
  "error": "BadRequest",
  "message": "Invalid format for x-firmly-device-id header"
}
The S2S secret token is missing, malformed, or not found in Firmly’s system.
{
  "error": "InvalidAPIToken",
  "message": "Invalid or missing API token"
}

​
Supported Endpoints

Server-to-Server authentication is supported on:

​
Next Steps

curl -X POST https://api.firmly.work/api/v1/discovery/search \
  -H "x-firmly-authorization: YOUR_S2S_SECRET" \
  -H "x-firmly-device-id: user-12345" \
  -H "Content-Type: application/json" \
  -d '{"query": "running shoes"}'