Skip to main content
POST
/
api
/
v1
/
browser-session
Browser Session
curl --request POST \
  --url https://api.firmly.work/api/v1/browser-session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-app-id: <x-firmly-app-id>' \
  --data '
{
  "access_token": "<string>"
}
'
{
  "device_created": true,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZXZpY2VfaWQiOiI4MmIxMDUyMi01NDgzLTQ3MTktYjU5OS02ZDc4YjEyODI3ZjAiLCJhcHBfaWQiOiJhcHAtMTIzNDU2IiwiZXhwIjoxNjg4OTk4NTcyLCJpYXQiOjE2ODg5OTQ5NzJ9.signature",
  "expires_in": 3600,
  "expires": 1688998572,
  "device_id": "82b10522-5483-4719-b599-6d78b12827f0"
}

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

Browser Session is the authentication endpoint that serves as the starting point for all Cart API integrations. It exchanges your Application ID for an access token that authenticates subsequent API calls.

​
Authentication

​
x-firmly-app-id
string
required
Your Application ID provided by Firmly

​
Request Body (Optional)

​
access_token
string
An expired access token (valid up to 1 week after expiration) to renew

​
Response

​
device_created
boolean
Indicates whether or not a new device was created for this session
​
access_token
string
The JWT access token to use in x-firmly-authorization header for all API calls
​
expires_in
number
Number of seconds until the token expires (typically 3600)
​
expires
number
Unix timestamp when the token expires
​
device_id
string
Unique identifier for this device session

​
Code Examples

curl -X POST https://api.firmly.work/api/v1/browser-session \
  -H "x-firmly-app-id: YOUR_APPLICATION_ID"

{
  "device_created": true,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZXZpY2VfaWQiOiI4MmIxMDUyMi01NDgzLTQ3MTktYjU5OS02ZDc4YjEyODI3ZjAiLCJhcHBfaWQiOiJhcHAtMTIzNDU2IiwiZXhwIjoxNjg4OTk4NTcyLCJpYXQiOjE2ODg5OTQ5NzJ9.signature",
  "expires_in": 3600,
  "expires": 1688998572,
  "device_id": "82b10522-5483-4719-b599-6d78b12827f0"
}

​
Token Renewal

You can renew an expired token up to 1 week after expiration: 
curl -X POST https://api.firmly.work/api/v1/browser-session \
  -H "x-firmly-app-id: YOUR_APPLICATION_ID" \
  -H "Content-Type: application/json" \
  -d '{"access_token": "EXPIRED_TOKEN"}'

​
Using the Access Token

After obtaining the access token, include it in all API requests: 
curl -X GET https://api.firmly.work/api/v2/domains/staging.luma.gift/cart \
  -H "x-firmly-authorization: YOUR_ACCESS_TOKEN"

​
Error Responses

Invalid or missing Application ID
{
  "error": "InvalidAppId",
  "message": "Application ID is invalid or not found"
}
Expired token cannot be renewed (older than 1 week)
{
  "error": "TokenExpired",
  "message": "Token is too old to renew"
}

​
Best Practices

  1. Token Refresh: Implement automatic token refresh before expiration. The authorization token represents the user’s device. It should be stored with the user; not with the backend
  2. Error Handling: Handle token expiration gracefully with retry logic

​
Implementation Example

class FirmlyAuth {
  constructor(appId) {
    this.appId = appId;
    this.token = null;
    this.expiresAt = null;
  }

  async getToken() {
    // Return existing token if still valid
    if (this.token && Date.now() < this.expiresAt) {
      return this.token;
    }

    // Get new token
    const response = await fetch('https://api.firmly.work/api/v1/browser-session', {
      method: 'POST',
      headers: { 'x-firmly-app-id': this.appId }
    });

    const data = await response.json();
    this.token = data.access_token;
    this.expiresAt = data.expires * 1000; // Convert to milliseconds
    
    return this.token;
  }
}

​
Next Steps

After authentication, you can: