POST /v1/device/session — Initialize Device Session

A device session is a short-lived token that ties a specific browser or app context to FraudEG’s device intelligence engine. When you attach a session_id to a transaction or identity call, FraudEG enriches the risk assessment with signals collected from that session — including device fingerprint, behavioral biometrics, bot likelihood, and whether the device has been seen and trusted before across the FraudEG network. Sessions expire after 30 minutes, so create one at the start of each user flow (login, checkout, onboarding) and attach it to every subsequent API call made within that flow.

Endpoint

POST https://api.fraudeg.com/v1/device/session

Request Headers

Header	Value	Required
`Authorization`	`Bearer <API_KEY>`	Yes
`Content-Type`	`application/json`	Yes

Request Body

string

required

The full URL of the page where the session is being initialized (e.g., "https://www.yourapp.com/checkout"). FraudEG uses this to contextualize behavioral signals and flag mismatches between the declared URL and the actual browsing context.

string

Your internal user ID. Provide this to associate the device session with a known user and link it to their existing behavioral profile and device history.

string

An intent hint that tells FraudEG which fraud model to weight most heavily for this session. Accepted values:

login — User is authenticating into an existing account.
checkout — User is completing a purchase flow.
onboarding — User is creating a new account.
account_change — User is modifying sensitive account details (e.g., password, payout method).

Response Fields

string

Unique session identifier. Pass this value as the session_id field in POST /v1/transactions/score and POST /v1/identity/verify to attach device intelligence to those calls.

string

ISO 8601 timestamp indicating when this session expires. Sessions are valid for 30 minutes from creation. After expiry, create a new session before making further API calls.

string

A persistent identifier for this device, stable across sessions and browser restarts. FraudEG generates this from a combination of hardware and software signals. Use it to track device-level history independently of sessions.

boolean

true if FraudEG has seen this device before across your account and it has a clean history. false for new or previously flagged devices. You can use this value to skip step-up authentication for returning users on trusted devices.

Code Examples

curl --request POST \
  --url https://api.fraudeg.com/v1/device/session \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "page_url": "https://www.yourapp.com/checkout",
    "user_id": "usr_8f3kd92",
    "action": "checkout"
  }'

const response = await fetch('https://api.fraudeg.com/v1/device/session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    page_url: 'https://www.yourapp.com/checkout',
    user_id: 'usr_8f3kd92',
    action: 'checkout',
  }),
});

const { session_id, device_trusted, expires_at } = await response.json();

// Attach session_id to your transaction score call
const scoreResponse = await fetch('https://api.fraudeg.com/v1/transactions/score', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 4999,
    currency: 'USD',
    session_id, // <-- attach here
    payment_method: { type: 'card', card_bin: '424242', last_four: '4242' },
    user: { id: 'usr_8f3kd92' },
  }),
});

Example Response

{
  "session_id": "sess_3hT9mKp2wZx",
  "expires_at": "2024-11-15T11:02:00Z",
  "device_id": "dev_7rQwP5nJxV",
  "device_trusted": true
}

Pass the session_id returned by this endpoint in the session_id field of both POST /v1/transactions/score and POST /v1/identity/verify. Without a session ID, those endpoints will score the request without device intelligence signals, which may reduce model accuracy — particularly for detecting account takeover and bot-driven fraud.

If your users access your platform through a web browser, use the FraudEG JavaScript snippet instead of calling this server-side endpoint directly. The JS snippet automatically creates a device session on page load, collects richer client-side signals (mouse movements, typing patterns, WebGL fingerprints), and exposes the session_id via fraudeg.getSessionId() for you to include in your checkout API call. Use this server-side endpoint for mobile apps, native desktop clients, or any environment without a browser context.

Overview

Transactions

Identity

Monitoring

POST /v1/device/session — Initialize Device Session

Endpoint

Request Headers

Request Body

Response Fields

Code Examples

Example Response

​Endpoint

​Request Headers

​Request Body

​Response Fields

​Code Examples

​Example Response

Endpoint

Request Headers

Request Body

Response Fields

Code Examples

Example Response