Authentication Guide — Internal API notes

This guide explains the authentication mechanisms available in the Oshun Platform API.

Table of Contents#

Overview
Authentication Methods
JWT Authentication
API Key Authentication
OAuth 2.0
Multi-Factor Authentication
Token Management
Security Best Practices

Overview#

The Oshun Platform uses a unified authentication system across all domains. All API requests must include valid credentials in the request headers.

Authentication Architecture#

text

┌─────────────────────────────────────────────────────────────────┐
│                         CLIENT                                   │
│  (Web App / Mobile App / API Consumer / SDK)                    │
└─────────────────────────────────┬───────────────────────────────┘
                                  │
                                  │ Credentials
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                      API GATEWAY                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                Authentication Layer                       │   │
│  │  • JWT Verification                                       │   │
│  │  • API Key Validation                                     │   │
│  │  • OAuth Token Validation                                 │   │
│  │  • Rate Limiting                                          │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────┬───────────────────────────────┘
                                  │
                                  │ Authenticated Request
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                      DOMAIN SERVICES                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │  Isis   │ │ Sophia  │ │ Hathor  │ │ Bellona │ │   ...   │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
└─────────────────────────────────────────────────────────────────┘

Authentication Methods#

Method	Use Case	Token Lifetime	Refresh
JWT Bearer	Web/mobile apps, user sessions	15 minutes	Yes (7 days)
API Key	Server-to-server, CLI tools, automation	Long-lived	Manual rotation
OAuth 2.0	Third-party integrations, partner apps	Configurable	Yes

JWT Authentication#

JWT (JSON Web Token) authentication is the primary method for user-facing applications.

Token Structure#

text

Header.Payload.Signature

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-001"
}
.
{
  "sub": "user_abc123",           // User ID
  "iss": "https://auth.oshun.io", // Issuer
  "aud": "https://api.oshun.io",  // Audience
  "exp": 1704067200,              // Expiration (Unix timestamp)
  "iat": 1704066300,              // Issued at
  "jti": "token_xyz789",          // Token ID (for revocation)
  "scope": "generation:write knowledge:read",
  "org": "org_def456",            // Organization ID (optional)
  "permissions": ["admin", "billing"]
}
.
[Signature]

Obtaining Tokens#

http

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

json

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "refreshToken": "rt_abc123xyz...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "scope": "generation:write knowledge:read"
}

Using Tokens#

Include the access token in the Authorization header:

http

GET /api/isis/generation/jobs
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Token Refresh#

When the access token expires, use the refresh token to obtain a new one:

http

POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "rt_abc123xyz..."
}

Response:

json

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "refreshToken": "rt_new456def...",
  "tokenType": "Bearer",
  "expiresIn": 900
}

Token Revocation#

To invalidate a token (e.g., on logout):

http

POST /auth/revoke
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{
  "token": "rt_abc123xyz...",
  "tokenTypeHint": "refresh_token"
}

API Key Authentication#

API keys are long-lived credentials for server-to-server communication.

Key Types#

Type	Prefix	Use Case
Live	`sk_live_`	Production environment
Test	`sk_test_`	Sandbox/testing environment
Restricted	`rk_`	Limited scope keys

Creating API Keys#

http

POST /api/keys
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Production Server",
  "permissions": ["generation:write", "generation:read"],
  "expiresAt": "2025-12-31T23:59:59Z",
  "ipAllowlist": ["203.0.113.0/24"],
  "rateLimit": {
    "requests": 1000,
    "period": "minute"
  }
}

Response:

json

{
  "id": "key_abc123",
  "key": "sk_live_abc123xyz789...",
  "name": "Production Server",
  "permissions": ["generation:write", "generation:read"],
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2025-12-31T23:59:59Z"
}

Important: The full API key is only shown once. Store it securely.

Using API Keys#

Include the API key in the X-API-Key header or Authorization header:

http

GET /api/isis/generation/jobs
X-API-Key: sk_live_abc123xyz789...

Or:

http

GET /api/isis/generation/jobs
Authorization: ApiKey sk_live_abc123xyz789...

Key Rotation#

Rotate keys periodically for security:

http

POST /api/keys/{keyId}/rotate
Authorization: Bearer {access_token}

Response:

json

{
  "id": "key_abc123",
  "key": "sk_live_newkey456...",
  "previousKey": "sk_live_abc123xyz789...",
  "previousKeyExpiresAt": "2024-01-22T10:30:00Z"
}

The previous key remains valid for 7 days to allow gradual migration.

OAuth 2.0#

OAuth 2.0 is used for third-party application integration.

Supported Grant Types#

Grant Type	Use Case
Authorization Code	Web applications with backend
Authorization Code + PKCE	Mobile apps, SPAs
Client Credentials	Server-to-server (no user context)

Authorization Code Flow#

Step 1: Redirect to Authorization#

text

https://auth.oshun.io/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://your-app.com/callback&
  response_type=code&
  scope=generation:write%20knowledge:read&
  state=random_state_string&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256

Step 2: User Authenticates#

The user logs in and approves the requested permissions.

Step 3: Handle Callback#

text

https://your-app.com/callback?code=auth_code_here&state=random_state_string

Step 4: Exchange Code for Tokens#

http

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=auth_code_here&
redirect_uri=https://your-app.com/callback&
client_id=your_client_id&
client_secret=your_client_secret&
code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Response:

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_oauth_abc123...",
  "scope": "generation:write knowledge:read"
}

Client Credentials Flow#

For server-to-server communication without user context:

http

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=your_client_id&
client_secret=your_client_secret&
scope=generation:write

Available Scopes#

Scope	Description
`generation:read`	Read generation jobs and outputs
`generation:write`	Create and manage generation jobs
`knowledge:read`	Search and read documents
`knowledge:write`	Ingest and manage documents
`world:read`	Read worlds and entities
`world:write`	Create and modify worlds
`build:read`	Read build configurations and status
`build:write`	Create and manage builds
`user:read`	Read user profile
`user:write`	Update user profile
`admin`	Full administrative access

Multi-Factor Authentication#

MFA adds an additional layer of security to user accounts.

Supported Methods#

Method	Description
TOTP	Time-based One-Time Password (Google Authenticator, Authy)
WebAuthn	Hardware security keys (YubiKey), biometrics
SMS	SMS verification codes (backup method)
Email	Email verification codes (backup method)

Enrolling MFA#

TOTP Setup#

http

POST /auth/mfa/totp/enroll
Authorization: Bearer {access_token}

Response:

json

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "backupCodes": [
    "abc12-def34",
    "ghi56-jkl78",
    ...
  ]
}

TOTP Verification#

http

POST /auth/mfa/totp/verify
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "code": "123456"
}

When MFA is enabled, login returns a challenge:

http

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response (MFA Required):

json

{
  "mfaRequired": true,
  "mfaToken": "mfa_challenge_token_xyz...",
  "availableMethods": ["totp", "webauthn"]
}

Complete MFA:

http

POST /auth/mfa/verify
Content-Type: application/json

{
  "mfaToken": "mfa_challenge_token_xyz...",
  "method": "totp",
  "code": "123456"
}

Token Management#

Viewing Active Sessions#

http

GET /auth/sessions
Authorization: Bearer {access_token}

Response:

json

{
  "sessions": [
    {
      "id": "sess_abc123",
      "device": "Chrome on macOS",
      "ip": "203.0.113.42",
      "location": "San Francisco, CA",
      "lastActive": "2024-01-15T10:30:00Z",
      "current": true
    },
    {
      "id": "sess_def456",
      "device": "Oshun iOS App",
      "ip": "198.51.100.23",
      "location": "New York, NY",
      "lastActive": "2024-01-14T15:45:00Z",
      "current": false
    }
  ]
}

Revoking Sessions#

http

DELETE /auth/sessions/{sessionId}
Authorization: Bearer {access_token}

Revoking All Sessions#

http

POST /auth/sessions/revoke-all
Authorization: Bearer {access_token}

Security Best Practices#

1. Store Tokens Securely#

Web Applications:

Store access tokens in memory only
Store refresh tokens in HTTP-only, secure cookies
Never store tokens in localStorage or sessionStorage

Mobile Applications:

Use platform secure storage (Keychain, Keystore)
Enable biometric protection

Server Applications:

Use environment variables or secret managers
Never commit credentials to version control

2. Implement Token Refresh#

typescript

// Example: Automatic token refresh
async function fetchWithAuth(url: string, options: RequestInit = {}) {
  let accessToken = getAccessToken();

  if (isTokenExpired(accessToken)) {
    const newTokens = await refreshTokens();
    accessToken = newTokens.accessToken;
    storeTokens(newTokens);
  }

  return fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${accessToken}`,
    },
  });
}

3. Validate Tokens Server-Side#

Always validate tokens on your backend before trusting them:

typescript

import { verify } from 'jose';

async function validateToken(token: string) {
  const JWKS = jose.createRemoteJWKSet(
    new URL('https://auth.oshun.io/.well-known/jwks.json')
  );

  const { payload } = await jose.jwtVerify(token, JWKS, {
    issuer: 'https://auth.oshun.io',
    audience: 'https://api.oshun.io',
  });

  return payload;
}

4. Use IP Allowlisting for API Keys#

Restrict API keys to specific IP ranges:

json

{
  "ipAllowlist": ["203.0.113.0/24", "198.51.100.0/24"]
}

5. Monitor for Suspicious Activity#

Set up alerts for failed authentication attempts
Monitor for unusual patterns (geographic anomalies, time-based)
Implement progressive delays for failed attempts

6. Rotate Credentials Regularly#

Credential Type	Recommended Rotation
API Keys	Every 90 days
OAuth Client Secrets	Every 180 days
Service Account Keys	Every 90 days

Error Responses#

Authentication Errors#

Code	HTTP Status	Description
`AUTH_INVALID_TOKEN`	401	Token is invalid or malformed
`AUTH_EXPIRED_TOKEN`	401	Token has expired
`AUTH_REVOKED_TOKEN`	401	Token has been revoked
`AUTH_INSUFFICIENT_SCOPE`	403	Token lacks required permissions
`AUTH_MFA_REQUIRED`	401	MFA verification required
`AUTH_RATE_LIMITED`	429	Too many authentication attempts

Example Error Response#

json

{
  "error": {
    "code": "AUTH_EXPIRED_TOKEN",
    "message": "The access token has expired",
    "details": {
      "expiredAt": "2024-01-15T10:30:00Z"
    }
  },
  "requestId": "req_abc123xyz"
}

Support#

Documentation: https://docs.oshun.io/authentication
API Status: https://status.oshun.io
Security Issues: security@oshun.io

Table of Contents#

Overview#

Authentication Architecture#

Authentication Methods#

JWT Authentication#

Token Structure#

Obtaining Tokens#

Login Flow#

Using Tokens#

Token Refresh#

Token Revocation#

API Key Authentication#

Key Types#

Creating API Keys#

Using API Keys#

Key Rotation#

OAuth 2.0#

Supported Grant Types#

Authorization Code Flow#

Step 1: Redirect to Authorization#

Step 2: User Authenticates#

Step 3: Handle Callback#

Step 4: Exchange Code for Tokens#

Client Credentials Flow#

Available Scopes#

Multi-Factor Authentication#

Supported Methods#

Enrolling MFA#

TOTP Setup#

TOTP Verification#

Login with MFA#

Token Management#

Viewing Active Sessions#

Revoking Sessions#

Revoking All Sessions#

Security Best Practices#

1. Store Tokens Securely#

2. Implement Token Refresh#

3. Validate Tokens Server-Side#

4. Use IP Allowlisting for API Keys#

5. Monitor for Suspicious Activity#

6. Rotate Credentials Regularly#

Error Responses#

Authentication Errors#

Example Error Response#

Support#