@paralyn/identity

Secure, zero-friction identity for AI-powered products.

Drop-in token signing for the PARALYN handoff flow. Your backend proves who the user is — PARALYN handles everything else. No passwords stored, no OAuth complexity, no shared secrets in the browser.

Overview

Add secure, role-aware AI to your product without building auth from scratch.

@paralyn/identity handles the trust layer between your backend and the PARALYN Platform. Your server signs a short-lived token that proves who the user is and what they're allowed to do — PARALYN verifies it and issues a scoped session. No passwords, no OAuth flows, no shared secrets in the browser.

Used by @paralyn/sdk to authenticate the embedded widget. Also available standalone if you need to sign tokens in your own backend (Node.js, Edge, Deno).

Installation

npm install @paralyn/identity

Handoff tokens

Sign a handoff token in your backend to initiate a PARALYN login:

import { signHandoffToken, createPlatformHandoffUrl } from "@paralyn/identity";

const token = await signHandoffToken(
  process.env.PARALYN_HANDOFF_SECRET!, // shared secret from workspace registration
  {
    sub: "user-123",          // your user's stable ID
    workspace: "acme-corp",
    tenant_id: "acme-corp",
    role: "user",             // "user" | "admin" | "developer" | "owner"
    email: "[email protected]",   // optional
    name: "Jane Smith",       // optional
  },
  600, // TTL in seconds (default: 120)
);

// Build the platform login URL
const loginUrl = createPlatformHandoffUrl(
  "https://paralynhq-ai.vercel.app",
  token,
  "/dashboard", // optional redirect path after sign-in
);

// Redirect your user to loginUrl

Verify a handoff token (done by the PARALYN API — you rarely need this):

import { verifyHandoffToken } from "@paralyn/identity";

const claims = await verifyHandoffToken(secret, token);
// { sub, workspace, tenant_id, role, email?, name? }

Session tokens

Sign and verify PARALYN access and refresh JWTs (used by the API gateway):

import { signAccessToken, verifyAccessToken } from "@paralyn/identity";

// Sign
const accessToken = await signAccessToken(jwtSecret, {
  sub: "user-123",
  workspace: "acme-corp",
  tenant_id: "acme-corp",
  role: "user",
});

// Verify
const claims = await verifyAccessToken(jwtSecret, accessToken);
// { sub, workspace, tenant_id, role, scoped_actions? }

Token claims reference

HandoffClaims

| Field | Type | Required | Description | |-------|------|----------|-------------| | sub | string | ✅ | Your user's stable external ID | | workspace | string | ✅ | Workspace slug | | tenant_id | string | ✅ | Tenant identifier (usually same as workspace) | | role | "user" \| "admin" \| "developer" \| "owner" | ✅ | User's role in the workspace | | email | string | | Optional email | | name | string | | Optional display name |

ParalynSessionClaims

| Field | Type | Description | |-------|------|-------------| | sub | string | User ID | | workspace | string | Workspace slug | | tenant_id | string | Tenant ID | | role | string | Role | | scoped_actions | string[] | Optional action allowlist |

Security

• Handoff secrets are generated once at workspace registration. Treat them like API keys — keep them server-side only.
• Handoff tokens have a short TTL (default 2 minutes) to limit replay window.
• All tokens use HS256 with a 256-bit secret minimum.

Related packages

| Package | Description | |---------|-------------| | @paralyn/sdk | React widget and workspace config |

License

AfriIntelligence — © PARALYN. All rights reserved.