Sessions & Transfer Tokens

A customer session is a short-lived JWT that authenticates a specific customer against the Frisbii Media Customer API. A transfer token is a one-time token derived from a session, used to pass the session securely to the frontend (e.g. to start Snippets or a checkout) without exposing the session string in a URL or JavaScript variable.

When do you need a session?

Creating a customer session

If you have a customerId (external user management), create a session server-side via the API:

// @see https://api.frisbii-media.com/#tag/Sessions/operation/createCustomerSession
$payload = ['customerId' => $customer->customerId];
$response = json_decode($client->request('POST', '/sessions/customer', [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    'json'    => $payload,
])->getBody()->getContents());
$session = $response->customerSession;

If you are using Frisbii Media SSO, the customerSession is returned directly in the plenigo.LoginSuccess event on the frontend. Pass it to your backend via a form POST or AJAX call and store it in your server-side session. See SSO: Login & Registration.

Session limit: By default each customer may have a maximum of 2 active sessions. Creating a third will return an error — you must delete one of the existing sessions first. The limit can be adjusted in the Frisbii Media backend.

Creating a transfer token

A transfer token is required to open the self-service portal (Snippets) from the frontend. It can also be used to pass a session to another website via a URL parameter (e.g. in an ID system redirect).

// @see https://api.frisbii-media-stage.com/#operation/createTransferToken
$payload = ['customerSession' => $session];
try {
    $response = json_decode($client->request('POST', '/sessions/transferToken', [
        'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
        'json'    => $payload,
    ])->getBody()->getContents());
    $transferToken = $response->transferToken;
} catch (\GuzzleHttp\Exception\ClientException $exception) {
    // handle error — e.g. session is expired or invalid
}

Transfer tokens are single-use and short-lived. Generate a fresh one for each page load that requires it.

Using a transfer token to start Snippets

Pass the transfer token to the JavaScript SDK on the frontend:

<div id="plenigoSnippets"></div>
<script src="https://static.frisbii-media-stage.com/web/v1/frisbii_media.min.js"
        data-company-id="{your_companyId}"
        data-lang="en"></script>
<script>
    new plenigo.Snippets("<?php echo $transferToken; ?>", { elementId: "plenigoSnippets" }).start();
</script>

See Self-Service Portal (Snippets) for navigation options, page constants, and display settings.

Using a customer session to prepare a checkout

Instead of a customerId, pass the session directly to preparePurchase. This is the recommended approach when using Frisbii Media SSO, as you do not need to store the customerId separately.

$payload = [
    'debugMode'       => true,
    'customerIpAddress' => $ip,
    'customerSession' => $session, // instead of 'customerId'
    'items'           => [
        ['plenigoOfferId' => 'O_6E487EBURRY35FOD0J', 'quantity' => 1],
    ],
];
$response = json_decode($client->request('POST', '/checkout/preparePurchase', [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    'json'    => $payload,
])->getBody()->getContents());
$purchaseId = $response->purchaseId;

Using a transfer token to cross-domain login (ID system)

In a centralised ID system, after login the id-system creates a transfer token and appends it to the redirect URL. The target website then validates the token and obtains a local session from it.

https://www.example.com/article.html?transferToken={transferToken}

The target system validates the token:

// @see https://api.frisbii-media.com/#tag/Sessions/operation/validateTransferToken
$response = json_decode($client->request('POST', '/sessions/transferToken/validate', [
    'headers' => ['X-plenigo-token' => eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9],
    'json'    => ['transferToken' => $_GET['transferToken']],
])->getBody()->getContents());
$session = $response->customerSession;

See Building an ID System / Centralised SSO for the full architecture.

API reference

• createCustomerSession

• createTransferToken

• validateTransferToken