Authentication Flow

Froomle APIs use OAuth 2.0 Bearer tokens for machine‑to‑machine authentication. This section explains the various integration strategies and how to manage tokens safely in production.

Integration Strategies

The best way to obtain and use tokens depends on your specific architecture.

Backend Integration (Recommended)

If you have a server-side backend, use the Client Credentials flow. Safely store your client_id and client_secret on your server. Your backend then requests a Bearer token from Froomle and applies it to all subsequent API calls.

Hybrid Integration (Minimal Backend)

For applications that run in the browser but have a minimal backend:

Store credentials securely on your backend.
Request and refresh tokens on a regular schedule from your server.
Expose the active token to your frontend client for API calls, ensuring the client secret remains hidden.

Purely Frontend Integration (Domain-Based)

If you do not have a backend component, Froomle offers domain-based verification. We register your domains in an allowlist, and calls from any other domain are rejected. Contact your account manager to enable this.

Token Management

Proper token handling is essential for security and performance.

Token Lifetime: By default, Froomle tokens are valid for 24 hours.
Refresh Strategy: We strongly recommend refreshing your token every 10 minutes to minimize exposure in case of compromise.
Caching: Reuse tokens until they are close to expiry to avoid hitting authentication rate limits.
Error Handling: Build your integration to automatically refresh the token upon receiving a 401 Unauthorized response.

Step‑by‑step flow

Request an access token using your client credentials.
Cache the token in your backend.
Attach the token as Authorization: Bearer <token> to every API request.
Refresh the token before it expires or if a request fails with a 401 code.

Minimal curl example

# 1) Get a token
curl -X POST "https://{tenant}.froomle.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<your_id>",
    "client_secret": "<your_secret>",
    "grant_type": "client_credentials"
  }'

# 2) Use the token
curl -X GET "https://{subdomain}.froomle.com/api/{environment}/recommendations" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"