API reference

Ban evasion across apps

The optional identifiers field — HMACs of e-mail address and phone number that link the user files of a tenant's apps. Coming soon.

Note: Coming soon. Ban evasion across apps is not part of a plan yet and is available on request: ask Limenia to enable it for your tenant. Until it is enabled and switched on, Limenia accepts identifiers and discards them silently, so sending them does no harm.

How it works

A tenant with several apps can let Limenia link the user files of its apps through the same e-mail address or phone number. Your backend never sends these values in plain text, only their HMAC with a key of the tenant. When a user whose linked user file in another app is currently banned or suspended becomes active in an app (a report about them, a review request, a signal, a device check, PUT /v1/subjects), Limenia creates the system signal ban_evasion_cross_app there, and a system rule of that app opens a case (category ban_evasion, priority high). A moderator decides; Limenia never sanctions on its own.

  • Links exist only between different apps of the same tenant that take part, never within one app and never across tenants. A ban or suspension that has ended does not count.
  • Apps with the same RevenueCat project are also linked by the same externalUserId, without identifiers.
  • Nothing changes for your backend apart from the optional field: responses, errors and webhooks stay the same. There is no webhook event for a link; your app learns about a case only through the decision (decision.created). The statement of reasons does not name the other app.

Setup

The owner sets it up in the dashboard: tenant settings, tab Ban evasion. Switch it on, confirm that a data protection impact assessment and a legal basis exist (the privacy notices of all chosen apps must cover the linking), and choose at least two apps that take part. New apps do not take part automatically. Then create a key:

  • Format lmid_{version}_{random}, e.g. lmid_1_ plus 43 characters of Base64url. The version (1 to 999) is part of the key.
  • It is shown exactly once. Limenia does not keep it and cannot show it again; if it is lost, create a new version (rotation below).
  • Store it as LIMENIA_IDENTIFIER_KEY in the secret store of the backend of every app that takes part: one key per tenant, so the same address gives the same HMAC in every app. Never put it in the mobile or web app; anyone could extract it from there and test addresses against it. The app never computes identifiers.
  • The dashboard shows per version the last characters of the key, a fingerprint and the check values (below) to compare with your backend.

Where to send them

Always for the user the request is about, never for the reporter.

Operation Field
POST /v1/reports subject.identifiers
POST /v1/reviews subject.identifiers
POST /v1/signals signals[i].identifiers
POST /v1/devices/check identifiers
PUT /v1/subjects/{externalUserId} identifiers

When to send them

Recommended: PUT /v1/subjects/{externalUserId} with identifiers at registration (that is when an evader shows up) and on every change of the e-mail address or phone number. Optionally also with reports, review requests, device checks and signals. A request without identifiers still counts: Limenia uses the identifiers it already stored for the user. A signal does not create a user, so send the identifiers of a new user with PUT /v1/subjects first.

Format

JSON
{ "keyVersion": 1, "email": "42a675f77f1e0efc8301553470878dd507fac6c79f4eb6099c0a0832e174ae0c", "phone": "733b02f032c851ae4b3d64094a9607ea2168ad054ab200a69144e4ee7b25ea38" }
Field Meaning
keyVersion Version of the key, 1 to 999; the number between lmid_ and the next _. Default the newest active version, but always send it.
email hex(HMAC-SHA256(key, "email:" + normalised address)), 64 lower-case hex characters. Optional.
phone hex(HMAC-SHA256(key, "phone:" + E.164 number)), 64 lower-case hex characters. Optional.
  • key is the whole key string as UTF-8 bytes (lmid_1_…), not Base64-decoded. The message is the kind, a colon and the normalised value as UTF-8, so an e-mail HMAC never equals a phone HMAC.
  • The whole object is at most 1 KB as JSON. Leave out a value you cannot normalise; never send an empty string.

Normalising the e-mail address

Limenia never sees the address and cannot check your normalisation, so it is deliberately simple and the same in every language:

  1. Remove leading and trailing whitespace (trim(), strings.TrimSpace, strip()).
  2. Lower only the ASCII letters A to Z. Every other character stays as it is (Unicode lower-casing differs between languages, e.g. for İ).
  3. If the result does not have exactly one @ with something before and after it, send no email.

No provider rules: dots and + suffixes stay, also at Gmail ([email protected] stays as it is). Removing them would merge different people at other providers.

Normalising the phone number

Bring it into E.164: +, country code, number without the national trunk prefix, digits only, at most 15 digits (0151 2345678 taken in Germany becomes +491512345678). Use libphonenumber (libphonenumber-js, phonenumbers, nyaruka/phonenumbers, phone_numbers_parser) with the region in which the app took the number. Spaces and hyphens may be removed. If the result does not match ^\+[1-9][0-9]{6,14}$, send no phone. Numbers are reassigned by carriers, so a link by phone is weaker than one by e-mail; the dashboard shows the kind of every link.

Test vectors

With the documentation key lmid_1_ExampleKeyForDocsOnly-NeverUseInProduction0 (never use it in production):

Message (kind:normalised value) HMAC
email:[email protected] 42a675f77f1e0efc8301553470878dd507fac6c79f4eb6099c0a0832e174ae0c
phone:+447700900123 733b02f032c851ae4b3d64094a9607ea2168ad054ab200a69144e4ee7b25ea38
email:[email protected] 1a0f78a6aefe96517a25604dc03dbe71f252da9b48425d6dc2d8ed886f7d78b5
phone:+447700900000 102f22e8bbbbb4c4f3837121507a585b63e64c0b86e72d3c547574ff369fd889
email:[email protected] c7b7f4b74624d534ae0f112eee1934bf4b286e47e624d72a9d4dee0559399216
email:mü[email protected] cd86b1938c0d1f3714785d49ef66ba77f6f00b7f465c9ca3b84d03cab72b96b4
phone:+491512345678 8eaddc5bacb7dbd05ae38df9803d29d7efdc1564f5ae82d32c44d25cb2557f50
Input Normalised
" [email protected] \n" [email protected]
"[email protected]" [email protected] (dots stay)
"MÜ[email protected]" mÜ[email protected] (only A to Z are lowered)
"max", "@example.com", "max@", "a@[email protected]" none, send no email
" +44 7700 900123 ", "+49-151-2345678" +447700900123, +491512345678
"01512345678", "+49 (0)151 2345678", "+123456" none (national, not E.164, too short), send no phone

Self-test with the check values

The check values in the dashboard are the HMACs of the fixed test values email:[email protected] (CHECK_EMAIL) and phone:+447700900000 (CHECK_PHONE) with your key; they contain no personal data. Compute both with your implementation and LIMENIA_IDENTIFIER_KEY and compare them with the dashboard, e.g. in a unit test or at backend start. If they match, key and implementation are right. With the documentation key they are the third and fourth rows of the test vectors.

Code

Code. Each snippet computes the identifiers object; all of them reproduce the test vectors.

Node.js (node:crypto):

JavaScript
import { createHmac } from "node:crypto";

const key = process.env.LIMENIA_IDENTIFIER_KEY; // lmid_<version>_<random>, backend only
const keyVersion = Number(key.split("_")[1]);
const hmac = (kind, value) => createHmac("sha256", key).update(`${kind}:${value}`, "utf8").digest("hex");

function normalizeEmail(raw) {
  const email = raw.trim().replace(/[A-Z]/g, (c) => c.toLowerCase());
  const at = email.indexOf("@");
  return at > 0 && at < email.length - 1 && email.indexOf("@", at + 1) === -1 ? email : undefined;
}

function normalizePhone(e164) {
  const phone = e164.trim().replace(/[ \t-]/g, "");
  return /^\+[1-9][0-9]{6,14}$/.test(phone) ? phone : undefined;
}

export function computeIdentifiers({ email, phone }) {
  const identifiers = { keyVersion };
  const e = email ? normalizeEmail(email) : undefined;
  if (e) identifiers.email = hmac("email", e);
  const p = phone ? normalizePhone(phone) : undefined;
  if (p) identifiers.phone = hmac("phone", p);
  return identifiers;
}

// At registration and on every change of e-mail address or phone number:
// PUT /v1/subjects/{externalUserId} with { identifiers: computeIdentifiers({ email: user.email, phone: user.phone }) }

Go (crypto/hmac):

Go
var e164 = regexp.MustCompile(`^\+[1-9][0-9]{6,14}$`)

type Identifiers struct {
	KeyVersion int    `json:"keyVersion"`
	Email      string `json:"email,omitempty"`
	Phone      string `json:"phone,omitempty"`
}

func identifierHMAC(key, kind, value string) string {
	m := hmac.New(sha256.New, []byte(key))
	m.Write([]byte(kind + ":" + value))
	return hex.EncodeToString(m.Sum(nil))
}

func normalizeEmail(raw string) (string, bool) {
	email := strings.Map(func(r rune) rune {
		if r >= 'A' && r <= 'Z' {
			return r + ('a' - 'A')
		}
		return r
	}, strings.TrimSpace(raw))
	local, domain, ok := strings.Cut(email, "@")
	if !ok || local == "" || domain == "" || strings.Contains(domain, "@") {
		return "", false
	}
	return email, true
}

func normalizePhone(raw string) (string, bool) {
	phone := strings.NewReplacer(" ", "", "\t", "", "-", "").Replace(strings.TrimSpace(raw))
	return phone, e164.MatchString(phone)
}

// key is os.Getenv("LIMENIA_IDENTIFIER_KEY").
func computeIdentifiers(key, email, phone string) (Identifiers, error) {
	rest, ok := strings.CutPrefix(key, "lmid_")
	v, _, ok2 := strings.Cut(rest, "_")
	version, err := strconv.Atoi(v)
	if !ok || !ok2 || err != nil {
		return Identifiers{}, errors.New("LIMENIA_IDENTIFIER_KEY is not an identifier key")
	}
	ids := Identifiers{KeyVersion: version}
	if e, ok := normalizeEmail(email); ok {
		ids.Email = identifierHMAC(key, "email", e)
	}
	if p, ok := normalizePhone(phone); ok {
		ids.Phone = identifierHMAC(key, "phone", p)
	}
	return ids, nil
}

Python (hmac):

Python
import hashlib, hmac, os, re

KEY = os.environ["LIMENIA_IDENTIFIER_KEY"]  # lmid_<version>_<random>, backend only
KEY_VERSION = int(KEY.split("_")[1])

def identifier_hmac(kind: str, value: str) -> str:
    return hmac.new(KEY.encode("utf-8"), f"{kind}:{value}".encode("utf-8"), hashlib.sha256).hexdigest()

def normalize_email(raw: str) -> str | None:
    email = re.sub(r"[A-Z]", lambda m: m.group().lower(), raw.strip())
    local, at, domain = email.partition("@")
    return email if at and local and domain and "@" not in domain else None

def normalize_phone(e164: str) -> str | None:
    phone = re.sub(r"[ \t-]", "", e164.strip())
    return phone if re.fullmatch(r"\+[1-9][0-9]{6,14}", phone) else None

def compute_identifiers(email: str | None = None, phone: str | None = None) -> dict:
    identifiers = {"keyVersion": KEY_VERSION}
    if email and (e := normalize_email(email)):
        identifiers["email"] = identifier_hmac("email", e)
    if phone and (p := normalize_phone(phone)):
        identifiers["phone"] = identifier_hmac("phone", p)
    return identifiers

Dart backend (package:crypto; the Flutter package limenia runs in the app and therefore has no such helper):

Dart
import 'dart:convert';
import 'dart:io';

import 'package:crypto/crypto.dart';

final _key = Platform.environment['LIMENIA_IDENTIFIER_KEY']!; // lmid_<version>_<random>, backend only
final _keyVersion = int.parse(_key.split('_')[1]);
final _e164 = RegExp(r'^\+[1-9][0-9]{6,14}$');

String _hmac(String kind, String value) =>
    Hmac(sha256, utf8.encode(_key)).convert(utf8.encode('$kind:$value')).toString();

String? normalizeEmail(String raw) {
  final email = raw.trim().replaceAllMapped(RegExp('[A-Z]'), (m) => m[0]!.toLowerCase());
  final at = email.indexOf('@');
  return at > 0 && at < email.length - 1 && !email.contains('@', at + 1) ? email : null;
}

String? normalizePhone(String e164) {
  final phone = e164.trim().replaceAll(RegExp(r'[ \t-]'), '');
  return _e164.hasMatch(phone) ? phone : null;
}

Map<String, Object> computeIdentifiers({String? email, String? phone}) {
  final e = email == null ? null : normalizeEmail(email);
  final p = phone == null ? null : normalizePhone(phone);
  return {
    'keyVersion': _keyVersion,
    if (e != null) 'email': _hmac('email', e),
    if (p != null) 'phone': _hmac('phone', p),
  };
}

Rotation

Limenia cannot convert old HMACs because it never knows the addresses, and identifiers only link within the same key version. To rotate (or after losing the key):

  1. The owner creates a new version in the dashboard. The old one stays active; both are accepted (at most two active versions).
  2. Deploy the new key to the backends of all apps that take part, compute with it from now on, and send the identifiers of your users again with PUT /v1/subjects/{externalUserId}, best for all users and at least for banned and suspended ones: their user files get identifiers of the new version only this way.
  3. Retire the old version. Its stored identifiers stay until their retention ends and keep linking among themselves. If the key leaked, retire it with deletion: Limenia then also deletes all identifiers of that version.

Retiring the only active version means Limenia accepts nothing until a new version exists.

Limenia never rejects anything because of identifiers

A request never fails and never answers differently because of identifiers, and the response does not say whether they were stored or linked. Limenia discards them silently when the feature is not enabled or switched off for the tenant, the app does not take part, the key version is unknown or retired, a value is not 64 hex characters, the object is not valid or over 1 KB, or (for signals) the user is unknown. The dashboard (tab Ban evasion) shows per app and day for the last 7 days how many identifiers were received, stored and discarded, with the reason. Check it after going live; discarded identifiers for a wrong format mean your normalisation or HMAC differs (compare the check values).

Data protection

Identifiers live as long as the user file they belong to and are deleted with it. Switching the feature off stops it at once and deletes all stored identifiers. The tenant needs its own data protection impact assessment and must name the linking in the privacy notices of all apps that take part.

See also Data protection.