Auth & Security

JWT Authentication Flow & Lifecycle

Standard JSON Web Token (JWT) issuance, verification, and role resolution. Authenticate against built-in developer test personas, decode signed HMAC-SHA256 claims, and access protected endpoints using standard Bearer authorization headers.

Select Test Persona

Choose a pre-configured role persona below to load credentials into the interactive login console:

Fetch Authenticated Profile (/auth/me)

Access protected user identity and claims using the session cookie or by passing the issued Bearer token:

Verify Session Identity & Claims

GET

response.json

{

// Click "Send" above to execute this request against the live server.

}

Update Authenticated Profile (PATCH /auth/me)

Apply partial mutations to your active user profile. Changes are stored in your session overlay without mutating baseline seed records:

Update User Profile Attributes

PATCH

response.json

{

// Click "Send" above to execute this request against the live server.

}

Register Custom Mock User (POST /auth/register)

Create an ad-hoc user account within your isolated sandbox session and immediately receive a signed JWT token pair:

Register New User & Obtain Tokens

POST

response.json

{

// Click "Send" above to execute this request against the live server.

}

JWT Claims Anatomy & Payload Structure

Access tokens issued by Playground API are signed with HMAC-SHA256 and encode identity and authorization claims:

1. JOSE HeaderHS256

{
  "alg": "HS256",
  "typ": "JWT"
}

Cryptographic signature algorithm metadata.

2. Token PayloadClaims

{
  "userId": 1,
  "username": "admin",
  "role": "ADMIN",
  "scopes": ["read:all","write:all","admin:all","sandbox:reset"],
  "iat": 1759140000,
  "exp": 1759140900
}

Identity, role permissions, and UNIX expiry timestamps.

3. SignatureHMAC

HMACSHA256(
  base64Url(header) + "." +
  base64Url(payload),
  JWT_SECRET
)

Tamper-evident verification hash ensuring authenticity.

Frontend Client Integration Recipes

Production-ready authorization interceptors and route protection patterns:

authClient.ts

// Modern Native TypeScript Fetch with Bearer Auth Header

interface AuthResponse {

access_token: string;

refresh_token: string;

token_type: string;

expires_in: number;

user: {

id: number;

name: string;

email: string;

role: string;

};

}

// 1. Authenticate and retrieve token pair

export async function loginUser(username: string, password = 'Password@123'): Promise<AuthResponse> {

const res = await fetch('https://playground.nileslabs.com/api/v1/auth/login', {

method: 'POST',

headers: { 'Content-Type': 'application/json' },

body: JSON.stringify({ username, password }),

});

if (!res.ok) {

const error = await res.json();

throw new Error(error.message || 'Login failed');

}

const authData: AuthResponse = await res.json();

localStorage.setItem('access_token', authData.access_token);

return authData;

}

// 2. Access protected endpoint using Bearer token

export async function getProfile() {

const token = localStorage.getItem('access_token');

const res = await fetch('https://playground.nileslabs.com/api/v1/auth/me', {

headers: {

Authorization: Bearer ${token},

});

return res.json();

}

PreviousOverview & Architecture

NextRefresh Token Rotation

JWT Authentication Flow & Lifecycle

Select Test Persona

Execute Login Request (System Administrator)

Login as admin

Fetch Authenticated Profile (/auth/me)

Verify Session Identity & Claims

Update Authenticated Profile (PATCH /auth/me)

Update User Profile Attributes

Register Custom Mock User (POST /auth/register)

Register New User & Obtain Tokens

JWT Claims Anatomy & Payload Structure

Frontend Client Integration Recipes

JWT Authentication Flow & Lifecycle

Select Test Persona

Execute Login Request (System Administrator)

Login as admin

Fetch Authenticated Profile (/auth/me)

Verify Session Identity & Claims

Update Authenticated Profile (PATCH /auth/me)

Update User Profile Attributes

Register Custom Mock User (POST /auth/register)

Register New User & Obtain Tokens

JWT Claims Anatomy & Payload Structure

Frontend Client Integration Recipes