Integration Guide

Patterns for integrating WardenAuth into your application.

Middleware Pattern

async function requireAccess(req, resource, action) {
  const result = await warden.hasAccess({
    subjectId: req.user.id,
    scopeId: req.workspace.id,
    resource,
    action,
  })
  if (!result.allowed) throw new ForbiddenError()
}

// Express
app.get('/api/documents/:id', async (req, res) => {
  await requireAccess(req, 'documents', 'read')
  // ... handler logic
})

Service Layer Pattern

class DocumentService {
  async getDocument(userId: string, workspaceId: string, docId: string) {
    await this.warden.hasAccess({
      subjectId: userId,
      scopeId: workspaceId,
      resource: 'documents',
      action: 'read',
    })

    return this.db.documents.findById(docId)
  }
}

Session Token Pattern

For browser/mobile clients, never expose your API key. Mint a session token:

// Server-side
const { token } = await warden.mintSessionToken({
  scopeId,
  permissionIds: ['documents:read'],
  ttlSeconds: 600,
})

// Pass token to client
res.json({ token })

// Client uses token for direct API calls
fetch('/api/documents', {
  headers: { Authorization: `Bearer ${token}` },
})

Bulk Check Pattern

Pre-compute what a user can see on a page:

const { results } = await warden.hasAccessBulk({
  subjectId: userId,
  scopeId,
  checks: [
    { resource: 'documents', action: 'read' },
    { resource: 'documents', action: 'create' },
    { resource: 'reports', action: 'read' },
    { resource: 'settings', action: 'update' },
  ],
})

const permissions = {
  canRead: results[0].allowed,
  canCreate: results[1].allowed,
  canSeeReports: results[2].allowed,
  canEditSettings: results[3].allowed,
}

// Use to conditionally render UI elements

API Gateway Pattern

# AWS API Gateway — Lambda authorizer
Authorizer:
  Type: COGNITO_USER_POOLS
  UserPoolArn: arn:aws:cognito-idp:...

The Cognito authorizer validates tokens. WardenAuth's Lambda authorizer resolves the user's identity, scope, and permissions — all before your handler runs. Your handler just calls hasAccess.

Key Rotation Pattern

// Register a webhook endpoint
await warden.createWebhook({
  url: 'https://api.myapp.com/webhooks/warden',
  events: ['api-key.rotated'],
})

// Webhook handler — receives rotationRef, fetches raw key
app.post('/webhooks/warden', async (req, res) => {
  const { newKeyId, rotationRef } = req.body
  const { rawKey } = await warden.revealRotation(scopeId, newKeyId, rotationRef)
  await secretsManager.update('WARDEN_KEY', rawKey)
  res.sendStatus(200)
})