To send a user through the Begini Psychometric Assessment, your server must first create a secure session. This returns a short-lived JWT access token which is then used to redirect the user directly into the assessment.

This call must be made server-side only. Never call the session API from client-side code.

Endpoint

POST https://api.begini.co/v1/sessions-management/tokens

Request headers

Your API key is unique per deployment and per environment (Test / Production). Find it in Beacon → Deployment Centre → select your deployment → Test or Production tab.

Request body

On UIDs: the UID links the assessment session back to a user in your system — typically your customer ID or application ID. It must not contain any personally identifiable information (PII) such as names, national IDs, or dates of birth. A UID can only be used once per event; if you need to re-score a user, add a prefix or suffix to create a new unique value.

Example request

curl --location --request POST 'https://api.begini.co/v1/sessions-management/tokens' \
--header 'api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "uid": "QWERT-YUIOP-ASDFGH",
  "integration_id": "1234567890987654321"
}'

Example response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "url": "https://api.begini.co/master/psychometrics"
}

Save the access_token. You will use it in the next step to redirect your user into the assessment.

Redirecting the user

Once you have the access token, redirect the user to the Begini Psychometric Assessment using the following URL:

https://app.psychometric.me/{access_token}

Replace {access_token} with the actual token value from the response. This redirect must be triggered server-side — the user's browser is then taken directly into the assessment.

Session time limit

Sessions expire after a configurable period. The default is 24 hours from the point the session is created (i.e. when the API is called), configurable from 1 to 10,000 hours in the Deployment Centre. If a user attempts to open an expired session link, they will be directed to your configured expiry URL. See Managing Deployments for redirect configuration.

HMAC authentication (optional, recommended)

By default the session API authenticates via the api-key header. For higher-security environments, Begini also supports HMAC signing of the session request.

Important: HMAC authentication must be enabled by Begini on your integration ID before use. Contact your account manager to have this configured.

When enabled, generate an HMAC SHA-512 signature of the JSON payload using your API key as the secret, and pass it in the X-Signature header alongside the request:

import hmac
import hashlib
import json
import requests

def generate_hash(message: str, secret_key: str) -> str:
    return hmac.new(
        secret_key.encode('utf-8'),
        msg=message.encode('utf-8'),
        digestmod=hashlib.sha512
    ).hexdigest()

api_key = 'YOUR_API_KEY'
payload = {
    "uid": "QWERT-YUIOP-ASDFGH",
    "integration_id": "1234567890987654321"
}

message = json.dumps(payload, separators=(',', ':'))
signature = generate_hash(message, api_key)

response = requests.post(
    'https://api.begini.co/v1/sessions-management/tokens',
    json=payload,
    headers={
        'api-key': api_key,
        'X-Signature': signature,
        'Content-Type': 'application/json'
    }
)

Note: the payload must be serialised with no spaces (separators=(',', ':')) — any formatting difference will produce a different hash and the request will fail.

Error responses

Test vs Production

Each deployment has separate API keys and Integration IDs for Test and Production. Ensure you are using the correct set for your environment. Test credentials will not work in production and vice versa. Only production data appears in the Beacon results screen.