Integrate

Calling the API

The base URL, the headers every call needs, and a small client you can copy.

The basics

Base URL: your Identise deployment, for example https://api.identise.com. All routes are under /v1.
JSON bodies (Content-Type: application/json) with camelCase fields.
X-Api-Key: <your key> on every /v1/oauth/* and /v1/platform/* call, except the Google sign-in URL and callback, which browsers use.
Most bodies include your appId. A key only works for the app it belongs to.
The tokens you get back are signed RS256 with your app's own key: see Verifying access tokens.

Forward your user's device

So that your users recognise their sessions, send the browser's User-Agent and X-Client-Ip: the user's IP address as your server saw it.

Identise uses X-Client-Ip only on requests whose API key is valid, and only if it is a plain IPv4 or IPv6 address; otherwise it records your server's own address. It never believes X-Forwarded-For from callers.

bash

curl -X POST https://api.identise.com/v1/oauth/login \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $IDENTISE_API_KEY" \
  -H "X-Client-Ip: 203.0.113.7" \
  -d '{"appId":"6f0c1d2e-3a4b-4c5d-8e9f-0a1b2c3d4e5f","email":"ada@example.com","password":"correct horse battery staple"}'

A small client

For Node 18 or later, in TypeScript. The other pages use it as identise(path, body).

const IDENTISE = process.env.IDENTISE_URL ?? "https://api.identise.com";
const APP_ID = process.env.IDENTISE_APP_ID!;
const API_KEY = process.env.IDENTISE_API_KEY!;

export async function identise<T>(
    path: string,
    body?: unknown,
    init: RequestInit & { clientIp?: string; userAgent?: string } = {},
): Promise<T> {
    const res = await fetch(`${IDENTISE}${path}`, {
        method: init.method ?? (body ? "POST" : "GET"),
        headers: {
            "Content-Type": "application/json",
            "X-Api-Key": API_KEY,
            ...(init.clientIp ? { "X-Client-Ip": init.clientIp } : {}),
            ...(init.userAgent ? { "User-Agent": init.userAgent } : {}),
        },
        body: body ? JSON.stringify({ appId: APP_ID, ...body }) : undefined,
    });
    if (res.status === 204) return undefined as T;
    const data = await res.json().catch(() => null);
    if (!res.ok) throw Object.assign(new Error(data?.detail ?? res.statusText), { status: res.status, code: data?.type });
    return data as T;
}

Errors come back as problem details with a stable type code: see Errors and rate limits.