Authentication

The Froomle APIs are protected using an OAuth 2.0 Bearer token flow for machine-to-machine (M2M) scenarios.

Depending on your integration setup, there are multiple ways to obtain and use these tokens.

Backend Integration

If you have a server-side backend available, we recommend using the Client Credentials flow. In this case, you safely store the provided client_id and client_secret on your backend. You then request a Bearer token using the Froomle authentication endpoint and apply that token to calls against Froomle’s APIs.

By default, tokens are valid for 24 hours, but we recommend refreshing them at least every 10 minutes (e.g., via a cron job or scheduled task).

Below is an example of a token request:

curl --request POST \
     --url "https://{tenant}.froomle.com/oauth/token" \
     --header "Content-Type: application/json" \
     --data '{
       "client_id": "{CLIENT_ID}",
       "client_secret": "{CLIENT_SECRET}",
       "grant_type": "client_credentials"
     }'

And a sample response:

{
  "access_token": "your_access_token",
  "expires_in": 86400,
  "scope": "write:items environment:{your_env}",
  "token_type": "Bearer"
}

Frontend Integration (With a Minimal Backend)

For applications that primarily run in the browser but still have some backend, the most secure approach is:

  1. Store the client_id and client_secret securely on your backend.

  2. Obtain and refresh the Bearer token from the Froomle authentication endpoint on a regular schedule.

  3. Expose that token to your frontend client for calling the Froomle APIs (Recommendations, Events, Items, etc.) without revealing the client secret.

If your application needs to update item metadata via the Items API, Froomle can provide a separate credential set dedicated to that usage. Please contact your Froomle representative for more information.

Purely Frontend Integration (Domain-Based Verification)

If you do not have any backend component and need to call Froomle directly from browser-based code, we offer domain-based verification. With this method:

  • Froomle will register your domain(s) in an allowlist.

  • Calls to Froomle from any other domain will be rejected.

To enable domain-based verification, please contact your Froomle account manager with a list of domains (including development or staging domains) you plan to use.

Token Lifetime

By default, Froomle tokens are valid for 24 hours. However, regardless of integration type, we strongly recommend refreshing tokens every 10 minutes or so to reduce exposure if a token is ever compromised.

Additional Resources

For more details on OAuth 2.0 Bearer tokens, see: Bearer Tokens in OAuth 2.0.