Headless Authentication (SSO)

The Headless Authentication API allows partners to securely authenticate location users into the Fyre interface without requiring them to enter credentials.

This mechanism is designed for POS partners and system integrators who want to provide seamless access to Fyre-powered features—such as Challenges—directly from their own environment. Authentication is performed using a temporary, one-time sign-in link generated via the API.

Purpose

Headless authentication enables partners to:

• Provide direct access to Fyre features from their own environment

• Embed Fyre interfaces within their platform using an iframe

• Redirect users into Fyre with a single click

• Eliminate credential management for Fyre accounts on the partner side.

The integration is designed to maintain strict security while minimizing friction for outlet users.

Typical use cases

Embedded Integration Fyre views, such as Challenges, can be embedded within a partner’s dashboard using an iframe. The one-time sign-in link authenticates the outlet user silently before loading the embedded interface.

Direct Redirect Partners may provide a "View My Challenges" button within their dashboard or email communications. When clicked, the user is automatically redirected to Fyre and authenticated instantly.

White-Labeling & Domains

If you are using a white-label version of the Fyre platform, the domain returned in the redirect_url will automatically match your configured environment.

• Standard: https://bo.fyre.app/auth?...

• White-Label: https://your-brand.com/auth?...

The API automatically determines the correct domain based on the fyre_id and partner configuration. You do not need to construct these URLs manually.

How it works

Instead of handling usernames and passwords, the partner system requests a temporary sign-in link for a specific location.

• Request: The partner’s backend calls the /auth/signin/request endpoint with a valid fyre_id.

• Receive: Fyre returns a redirect_url. This link is valid for 5 minutes and can be used once.

• Redirect: The partner redirects the user’s browser (or iframe source) to the returned URL.

• Session: Fyre validates the token embedded in the URL and establishes a secure session for that location.

Security model

Headless authentication is built around strict security controls:

• No Passwords: No passwords are exchanged or stored by the partner.

• Short-Lived: tokens expire automatically after 5 minutes.

• Single-Use: The link cannot be reused after a successful sign-in.

• Scoped Access: Authentication is strictly scoped to the specific fyre_id provided.

Partners must ensure that API requests are made from secure backend environments. API keys must never be exposed in client-side code.

Request location one-time sign-in link

post

Generate a short-lived, one-time URL to auto-authenticate a specific location into the Fyre interface.

Note on Domains: The domain in the returned redirect_url will vary depending on your white-label configuration (e.g., bo.fyre.app vs your-brand.com).

Required Permission: locations.auth.link

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Standard API Key authentication.

Body

application/json

fyre_idstringRequired

The unique identifier for the location.

Example: FR0100000000

Responses

200

Success. Use the returned URL to redirect the user.

application/json

401

Unauthorized

application/json

post

/auth/signin/request

cURLJavaScript (Axios)

curl --request POST \
  --url https://api.fyre.app/api/v1/auth/signin/request \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_TOKEN' \
  --data '{
	"fyre_id": "FR0100000000"
}'

{
  "redirect_url": "https://bo.fyre.app/auth?oobCode=GKJ8HBnlVvHHNblJV5hojyCZu3cr3OcP7dkQuzOPS5w2GUwZpufr3j&mode=login"
}