Skip to main content

​
Overview

Terang AI supports Single Sign-On (SSO) via signed JWT tokens. Your organization signs a JWT with your private key, and Terang AI verifies it using your public key. This allows your members to access Terang AI directly from your platform without creating a separate account.

​
JWT Specification

Use the RS256 algorithm: 
{
  "alg": "RS256",
  "typ": "JWT"
}

​
Payload

{
  "iss": "iai.or.id",
  "aud": "terang.ai",
  "sub": "member",
  "email": "andi@iai.or.id",
  "membershipId": "0001234",
  "iat": 1710000000,
  "exp": 1710000300,
  "jti": "unique-token-id"
}
FieldTypeRequiredDescription
issstringYesYour domain (e.g. iai.or.id)
audstringYesMust be terang.ai
substringYesSubject type, e.g. member
emailstringYesMember’s email address
membershipIdstringYesUnique member ID in your system
iatnumberYesIssued at (Unix timestamp)
expnumberYesExpiration (Unix timestamp, max 5 minutes)
jtistringYesUnique token ID to prevent replay attacks
The exp must be at most 5 minutes after iat. Tokens with a longer expiry will be rejected.

​
Public Key Exchange

Terang AI needs your public key to verify JWT signatures. You have two options: Expose your public key at a standard JWKS endpoint. This supports key rotation automatically. 
GET https://your-domain.com/.well-known/jwks.json
Response format: 
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id-1",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}
Share your JWKS URL with the Terang AI team, and we will configure it on our end.

​
Option 2: Share Public Key Directly

If you cannot host a JWKS endpoint, you can share the PEM-formatted public key directly with the Terang AI team. 
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----
If your key changes, you must notify the Terang AI team to update it manually. We strongly recommend Option 1 for production use.

​
SSO Flow

Once the JWT is ready, redirect the user to: 
https://iai.terang.ai/api/auth/sso?token=<JWT_TOKEN>
Terang AI will:
  1. Verify the JWT signature using your public key
  2. Validate iss, aud, exp, and jti claims
  3. Find or create the user account based on email and membershipId
  4. Redirect the user to the dashboard

​
Implementation Examples

​
PHP

<?php
// Generate a new RSA key pair (run once)
$config = [
    'private_key_bits' => 2048,
    'private_key_type' => OPENSSL_KEYTYPE_RSA,
];

$keyPair = openssl_pkey_new($config);

// Export private key (keep this secret!)
openssl_pkey_export($keyPair, $privateKey);
file_put_contents('private_key.pem', $privateKey);

// Export public key (share with Terang AI)
$publicKey = openssl_pkey_get_details($keyPair)['key'];
file_put_contents('public_key.pem', $publicKey);

echo "Keys generated successfully.\n";
echo "Share public_key.pem with the Terang AI team.\n";

​
Node.js

import jwt from 'jsonwebtoken';
import { randomUUID } from 'crypto';
import fs from 'fs';

const privateKey = fs.readFileSync('./private_key.pem', 'utf8');

const token = jwt.sign(
  {
    iss: 'iai.or.id',
    aud: 'terang.ai',
    sub: 'member',
    email: member.email,
    membershipId: member.id,
    jti: randomUUID(),
  },
  privateKey,
  {
    algorithm: 'RS256',
    expiresIn: '5m',
  }
);

// Redirect user
res.redirect(`https://iai.terang.ai/api/auth/sso?token=${token}`);

​
Testing

You can decode and inspect your JWT at jwt.io before sending it to Terang AI. Checklist:
  • JWT header uses RS256 algorithm
  • All required payload fields are present
  • aud is set to terang.ai
  • exp is within 5 minutes of iat
  • jti is unique per request
  • Public key is shared with Terang AI (via JWKS or PEM)