Component Sessions

A session token is a short-lived, secure credential used to authenticate an embedded component. The session lifecycle is designed to be both secure and easy to integrate:

Creation

Your backend server initiates a request to the Reporting API using your secret Merchant Central or Gateway API key to create a new session. In the request payload, you should specify either gateway or merchant-central. Setting both will result in a request validation error.

Initialization:

The API returns a temporary session_token, which your server passes to the client application to initialize the embedded component.

Authentication:

The embedded component uses the session_token to securely communicate with Reporting API service and retrieve the data required for rendering.

Expiration & Rotation:

Session tokens automatically expire after a predefined duration (15 minutes by default). The component can be configured to proactively request a new session from your backend before expiration, ensuring a seamless and uninterrupted user experience.

sequenceDiagram
    participant Client as Client Application
    participant Backend as Merchant Backend
    participant API as Reporting API
    participant Component as Embedded Component

    Backend->>API: Create session (API key)
    API-->>Backend: session_token
    Backend-->>Client: session_token
    Client->>Component: Initialize with session_token
    Component->>API: Authenticated requests (session_token)
    API-->>Component: Component data