> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudeg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/device/session — Initialize Device Session

> POST /v1/device/session — initialize a FraudEG device intelligence session. Returns a session_id to attach to transaction and identity API calls.

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

```http theme={null}
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

<ParamField body="page_url" type="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.
</ParamField>

<ParamField body="user_id" type="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.
</ParamField>

<ParamField body="action" type="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).
</ParamField>

## Response Fields

<ResponseField name="session_id" type="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.
</ResponseField>

<ResponseField name="expires_at" type="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.
</ResponseField>

<ResponseField name="device_id" type="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.
</ResponseField>

<ResponseField name="device_trusted" type="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.
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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' },
    }),
  });
  ```
</CodeGroup>

### Example Response

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

<Note>
  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.
</Note>

<Tip>
  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.
</Tip>