Unity

Authentication

Every conversation starts with the game proving which account it belongs to. Project Settings → PERSONAIZER → Mode picks how:

ModeWhat the game sendsYour account key
API Key (default)Your account API key, as X-Api-KeyShips inside the build
Server TokenA short-lived token from your own server, as X-End-User-TokenStays on your server

The Persona ID on each Persona Character is public in both modes: it names the persona and grants no access on its own.

API Key mode

Paste your account API key (dashboard: Profile → API access) and press Connect. Nothing else to run.

The key is saved in your settings asset and ships inside every build, where a determined player can extract it. Whether that's acceptable is your call: it's the quickest way to a working game, and the persona's session limits on the dashboard cap what any one session can spend. If the key leaks, rotate it on your profile and ship a build with the new one.

This is also the only mode where the Editor shows Usage (your plan's credits and minutes), because it's the only mode where Unity holds a key that can read it. In Server Token mode, see usage in the dashboard.

Server Token mode

Your server keeps the account's Identity Secret (on your profile, beside the API key) and signs a short-lived token for each conversation. The game never holds a long-lived credential.

  1. Set Mode to Server Token.
  2. Set Token Endpoint to your server's URL, for example https://game.example.com/personaizer-token.
  3. Run a token server at that URL (below).

Each time a Persona Character connects, the game sends:

POST /personaizer-token
Content-Type: application/json

{"install_id": "3f2b9c0e8d7a4b1e9c6f5a2d1e0b7c84"}

install_id is a random id the package creates once per install and keeps in PlayerPrefs. Your server answers 200 with:

{"token": "<identity token>"}

The token is the identity token described on Authentication → Identity token: HS256, signed with your Identity Secret, sub = the player's id, iat, and an exp at most 10 minutes ahead (1 minute of clock skew is allowed). Mint a fresh one for every request.

Token server: Node

// npm install express jsonwebtoken
import express from "express";
import jwt from "jsonwebtoken";

const app = express();
app.use(express.json());

app.post("/personaizer-token", (req, res) => {
  // Your own player id if the player is logged in; otherwise the install id the game sends.
  const playerId = req.body?.install_id;
  if (!playerId) return res.status(400).end();

  const token = jwt.sign(
    { sub: String(playerId) },               // jsonwebtoken adds iat
    process.env.PERSONAIZER_IDENTITY_SECRET,
    { algorithm: "HS256", expiresIn: "5m" },
  );
  res.json({ token });
});

app.listen(3000);

Token server: Python

# pip install flask pyjwt
import os, time
import jwt
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET = os.environ["PERSONAIZER_IDENTITY_SECRET"]

@app.post("/personaizer-token")
def personaizer_token():
    # Your own player id if the player is logged in; otherwise the install id the game sends.
    player_id = (request.get_json(silent=True) or {}).get("install_id")
    if not player_id:
        return "", 400

    now = int(time.time())
    token = jwt.encode({"sub": str(player_id), "iat": now, "exp": now + 300}, SECRET, algorithm="HS256")
    return jsonify(token=token)

Get the token your own way

If your game already talks to its own backend, with its own login, get the token there instead of from the Token Endpoint. Set PersonaAuth.TokenProvider before any Persona Character connects; when it's set, the package calls it in place of the endpoint:

using Personaizer;

// e.g. in your login flow, once the player is signed in
PersonaAuth.TokenProvider = async ct => await MyBackend.GetPersonaizerTokenAsync(ct);

Return a fresh token on every call. Your backend signs it exactly like the servers above, with your own player id as sub.

Shipping a secure build

  • Use Server Token mode for any build you hand to players you don't know. The build then holds only your Token Endpoint URL and Persona IDs, which are safe to ship; an API key entered earlier stays in the Editor and never goes into the build.
  • Keep the Identity Secret on your server. Never in a scene, a ScriptableObject, a build, or your repository. If it leaks, rotate it on your profile: tokens signed with the old secret stop working at once, so update your server first.
  • Decide who gets a token. The Token Endpoint is public. With a login of your own, check the player's session before signing and use your player id as sub, so each player's history follows them. Without one, sign the install_id and rate-limit the endpoint.
  • Keep the settings asset out of public repositories in API Key mode: Assets/Settings/PERSONAIZER.asset holds the key.
  • Set session limits on each persona in the dashboard, so no single conversation can run up your plan.

Errors from either mode, with fixes, are on Troubleshooting. The codes behind them are on Errors & limits.