Skip to main content

​
Authentication guide

This page explains how to integrate authentication flows and includes endpoint-level request and response examples.
Primary API reference: API Explorer in the sidebar.
1

Sign in

Call POST /api/auth/login and keep accessToken in memory.
2

Call protected APIs

Add Authorization: Bearer <access-jwt> on protected requests.
3

Handle expiration

On 401, call POST /api/auth/refresh once and retry original request once.
4

Verify scope

Use GET /api/auth/me to validate user and tenant scope in session bootstrap.
5

Sign out

Call POST /api/auth/logout and clear client session state.

​
Security requirements

Do not store long-lived credentials in browser local storage. Keep refresh-token handling scoped and protected.
  • Use HTTPS end-to-end.
  • Use short access-token TTL and rotation via refresh endpoint.
  • Fail closed: if refresh fails, clear session and redirect to sign-in.

​
Endpoint index

  • POST /api/auth/login
  • POST /api/auth/refresh
  • GET /api/auth/me
  • POST /api/auth/logout

​
Endpoint examples

​
POST /api/auth/login

curl -X POST "<NSDK_API_BASE_URL>/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "<password>"
  }'

{
  "accessToken": "jwt.access.token",
  "refreshToken": "jwt.refresh.token",
  "userId": "1005",
  "tenantId": "2001"
}

{
  "detail": "Unauthorized",
  "request_id": "req_abc123"
}

​
POST /api/auth/refresh

curl -X POST "<NSDK_API_BASE_URL>/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "<refresh-jwt>"
  }'

{
  "accessToken": "jwt.new.access.token",
  "refreshToken": "jwt.new.refresh.token"
}

{
  "detail": "Unauthorized",
  "request_id": "req_abc123"
}

​
GET /api/auth/me

curl "<NSDK_API_BASE_URL>/api/auth/me" \
  -H "Authorization: Bearer <access-jwt>"

{
  "userId": "1005",
  "tenantId": "2001",
  "email": "user@example.com"
}

{
  "detail": "Unauthorized",
  "request_id": "req_abc123"
}

​
POST /api/auth/logout

curl -X POST "<NSDK_API_BASE_URL>/api/auth/logout" \
  -H "Authorization: Bearer <access-jwt>"

{
  "ok": true
}

{
  "detail": "Rate limit exceeded",
  "request_id": "req_abc123"
}

​
Error handling baseline

  • 400: request payload shape invalid.
  • 401: credentials invalid or token expired.
  • 429: retry with backoff.
  • 500: retry with request_id and escalate if persistent.