Browser Session

POST

api

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>"
}
'

import requests

url = "https://api.firmly.work/api/v1/browser-session"

payload = { "access_token": "<string>" }
headers = {
    "x-firmly-app-id": "<x-firmly-app-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-firmly-app-id': '<x-firmly-app-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({access_token: '<string>'})
};

fetch('https://api.firmly.work/api/v1/browser-session', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/api/v1/browser-session",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'access_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-firmly-app-id: <x-firmly-app-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firmly.work/api/v1/browser-session"

	payload := strings.NewReader("{\n  \"access_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-firmly-app-id", "<x-firmly-app-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firmly.work/api/v1/browser-session")
  .header("x-firmly-app-id", "<x-firmly-app-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/api/v1/browser-session")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-firmly-app-id"] = '<x-firmly-app-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

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

string

required

Your Application ID provided by Firmly

Request Body (Optional)

string

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

Response

boolean

Indicates whether or not a new device was created for this session

string

The JWT access token to use in x-firmly-authorization header for all API calls

number

Number of seconds until the token expires (typically 3600)

number

Unix timestamp when the token expires

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"

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

const { access_token, expires_in } = await response.json();
console.log(`Token expires in ${expires_in} seconds`);

import requests

response = requests.post(
    'https://api.firmly.work/api/v1/browser-session',
    headers={'x-firmly-app-id': 'YOUR_APPLICATION_ID'}
)

data = response.json()
access_token = data['access_token']
expires_in = data['expires_in']
print(f"Token expires in {expires_in} seconds")

{
  "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"}'

curl -X POST https://api.firmly.work/api/v1/browser-session \
  -H "x-firmly-app-id: YOUR_APPLICATION_ID" \
  -H "Cookie: fsession_v2=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

400 Bad Request

Invalid or missing Application ID

{
  "error": "InvalidAppId",
  "message": "Application ID is invalid or not found"
}

401 Unauthorized

Expired token cannot be renewed (older than 1 week)

{
  "error": "TokenExpired",
  "message": "Token is too old to renew"
}

Best Practices

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
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:

Get Cart - Retrieve the current cart
Browse Products - View available products
Add to Cart - Add items to cart

⌘I

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>"
}
'

import requests

url = "https://api.firmly.work/api/v1/browser-session"

payload = { "access_token": "<string>" }
headers = {
    "x-firmly-app-id": "<x-firmly-app-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-firmly-app-id': '<x-firmly-app-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({access_token: '<string>'})
};

fetch('https://api.firmly.work/api/v1/browser-session', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/api/v1/browser-session",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'access_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-firmly-app-id: <x-firmly-app-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firmly.work/api/v1/browser-session"

	payload := strings.NewReader("{\n  \"access_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-firmly-app-id", "<x-firmly-app-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firmly.work/api/v1/browser-session")
  .header("x-firmly-app-id", "<x-firmly-app-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/api/v1/browser-session")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-firmly-app-id"] = '<x-firmly-app-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Authentication

Request Body (Optional)

Response

Code Examples

Token Renewal

Using the Access Token

Error Responses

Best Practices

Implementation Example

Next Steps

​Overview

​Authentication

​Request Body (Optional)

​Response

​Code Examples

​Token Renewal

​Using the Access Token

​Error Responses

​Best Practices

​Implementation Example

​Next Steps

Overview

Authentication

Request Body (Optional)

Response

Code Examples

Token Renewal

Using the Access Token

Error Responses

Best Practices

Implementation Example

Next Steps