Scoped Auth

Name: Surf
Author: Surf

Fine-grained permission scopes for commands

Scoped Auth#

Scoped auth lets you attach permission scopes to tokens and require specific scopes on individual commands. Use scopedVerifier to map tokens to scopes, and requiredScopes on commands to enforce them.

typescript

import { createSurf, scopedVerifier } from '@surfjs/core'
 
const surf = await createSurf({
  name: 'My API',
 
  // scopedVerifier maps tokens → their allowed scopes
  authVerifier: scopedVerifier({
    'sk-readonly-token':  ['catalog:read'],
    'sk-admin-token':     ['catalog:read', 'catalog:write', 'orders:write'],
  }),
 
  commands: {
    // Public — no auth needed
    search: {
      description: 'Search products',
      params: { query: { type: 'string', required: true } },
      run: async ({ query }) => db.search(query),
    },
 
    // Requires auth + specific scope
    'product.create': {
      description: 'Create a product',
      auth: 'required',
      requiredScopes: ['catalog:write'],
      params: { name: { type: 'string', required: true } },
      run: async ({ name }, ctx) => db.products.create({ name }),
    },
 
    // Orders scope — returns 403 if token lacks 'orders:write'
    'order.create': {
      description: 'Create an order',
      auth: 'required',
      requiredScopes: ['orders:write'],
      run: async (params, ctx) => db.orders.create(ctx.claims!.token, params),
    },
  },
})

💡 Tip: Scopes are checked after token validity — a token must be valid AND have all requiredScopes or the request returns 403. Use ctx.scopes in your handler to inspect which scopes the token carries.

For fine-grained access control with JWT tokens:

typescript

import { createSurf, scopedVerifier } from '@surfjs/core'
 
const surf = await createSurf({
  name: 'My API',
  auth: { type: 'bearer', description: 'OAuth2 Bearer token with scopes' },
 
  // scopedVerifier checks requiredScopes against token scopes
  authVerifier: scopedVerifier(async (token) => {
    const decoded = await verifyJWT(token)
    if (!decoded) return { valid: false, reason: 'Invalid token' }
    return {
      valid: true,
      claims: { userId: decoded.sub },
      scopes: decoded.scopes,  // e.g. ['read:products', 'write:orders']
    }
  }),
 
  commands: {
    // Requires specific scopes
    'order.create': {
      description: 'Create an order',
      auth: 'required',
      requiredScopes: ['write:orders'],
      run: async (params, ctx) => orders.create(ctx.claims!.userId, params),
    },
 
    // Multiple required scopes (all must be present)
    'admin.analytics': {
      description: 'View analytics dashboard',
      auth: 'hidden',
      requiredScopes: ['read:analytics', 'admin'],
      run: async () => getAnalytics(),
    },
  },
})

When a token lacks a required scope, Surf returns a 403 AUTH_FAILED response with details about the missing scopes. Scopes are also advertised in the manifest so agents know what permissions are needed.

Edit this page on GitHub

PreviousAuthentication Next Security Best Practices