Authentication Flow

Froomle APIs use OAuth 2.0 Bearer tokens for machine-to-machine authentication. This page defines the public authentication contract for customer integrations.

Use the public Froomle authentication endpoint for your tenant:

POST https://<tenant>.froomle.com/oauth/token

Required token request contract

Request tokens with the OAuth 2.0 Client Credentials flow.

Field Required Value

client_id

Yes

The client ID provided by Froomle.

client_secret

Yes

The client secret provided by Froomle. Keep this secret on your backend.

grant_type

Yes

client_credentials

Send the token request as application/x-www-form-urlencoded:

curl -X POST "https://<tenant>.froomle.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<your_client_id>" \
  --data-urlencode "client_secret=<your_client_secret>"

Scope and audience behavior

Froomle assigns API permissions to your client credentials. The issued token contains the scopes that are configured for that client.

Do not send a scope parameter when requesting a token. Requested scopes are not how Froomle grants API access. Froomle grants access by the client credentials that were provisioned for your integration.

Do not send an audience parameter. The token audience is configured by Froomle for the tenant project.

Parameter Contract

scope

Omit it. Access scopes are assigned to the client credentials by Froomle.

audience

Omit it. The audience is assigned by Froomle.

Sending scope or audience in the token request does not grant extra API access. API access is controlled by the client credentials that Froomle provides.

Token response

A successful token response contains an access token:

{
  "access_token": "...",
  "expires_in": 86400,
  "scope": "environment:* full:all",
  "token_type": "Bearer"
}

Use the access_token value as a Bearer token on subsequent API requests:

curl -X GET "https://<tenant>.froomle.com/api/<environment>/recommendations" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json"

The token is a JWT signed by Froomle’s tenant authentication service. Treat the token as a credential and do not expose it unnecessarily.

Token lifetime and refresh

Proper token handling is required for reliable production integrations.

  • Tokens are valid for a limited time. The default lifetime is 24 hours.

  • Cache and reuse a token until it is close to expiry.

  • Refresh proactively from your backend. A refresh interval of about 10 minutes is a safe default for most integrations.

  • If an API request returns 401 Unauthorized, request a new token and retry once before surfacing the error.

  • Never cache tokens indefinitely.

JWKS endpoint

If your backend needs to validate Froomle-issued tokens itself, use the public JWKS endpoint for the tenant:

GET https://<tenant>.froomle.com/.well-known/jwks.json

Most customer integrations only call Froomle APIs and do not need to validate tokens locally. If you do validate tokens, cache the JWKS response and refresh it when token validation fails because signing keys can rotate.

Integration strategies

Backend integration (recommended)

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

Hybrid integration with a minimal backend

For browser applications that have a minimal backend:

  • Store OAuth credentials on your backend.

  • Request and refresh tokens on the backend.

  • Expose only a short-lived active token to your frontend when the frontend must call an authenticated recommendation endpoint.

  • Never expose client_secret in browser code, mobile apps, or static assets.

Frontend SDK recommendation auth

If you use @froomle/frontend-sdk in the browser and recommendation requests require auth:

  • Keep OAuth credentials on your backend.

  • Pass only a short-lived bearer token to the browser.

  • Configure the SDK with either a static token or an async token provider before the first recommendation request.

  • Recommendation auth in the SDK applies to recommendation requests only; tracked events remain unauthenticated.

For the SDK-specific API and timing rules, see Recommendation Authentication.

Pure frontend integration

Do not request OAuth tokens directly from a browser. Calling /oauth/token from frontend code would expose credentials or tokens to visitors.

If your integration has no backend component, Froomle can provide domain-based verification for supported frontend use cases. Contact your account manager to enable this.

For DNS and SDK configuration when using a custom subdomain, see Custom domain (CNAME).

Contract summary

The Froomle authentication contract is:

  • POST https://<tenant>.froomle.com/oauth/token

  • OAuth 2.0 Client Credentials

  • client_id, client_secret, and grant_type=client_credentials

  • Bearer token response with access_token

  • API requests authenticated with Authorization: Bearer <access_token>

Related topics