Node.js

npm install @hyper.authio/express        # an Express API (brings server and client)
npm install @hyper.authio/server         # an API on another framework
npm install @hyper.authio/client         # a worker, a CLI, or calls to Authio
npm install -D @hyper.authio/testing     # tests

AUTHIO_ISSUER=https://authio.api.hyperio.tech/realms/acme
AUTHIO_CLIENT_ID=orders-worker
AUTHIO_CLIENT_SECRET=YOUR_CLIENT_SECRET

import express from 'express'
import { authioBearer, requirePermission, requireScope } from '@hyper.authio/express'

const app = express()

app.use(
  '/api',
  authioBearer({
    issuer: process.env.AUTHIO_ISSUER!,
    audiences: 'https://api.example.com',
  }),
)

app.get('/api/me', (req, res) => {
  res.json(req.authio!.user)
})

app.get('/api/orders', requireScope('orders:read'), requirePermission('orders', 'read'), (req, res) => {
  res.json([])
})

app.listen(3001)

import {
  anyOf,
  requireAuthenticationLevel,
  requireAuthio,
  requireClaim,
  requireGroup,
  requireOrganization,
  requirePermission,
  requireRole,
  requireScope,
} from '@hyper.authio/express'

// Any of the scopes; pass 'all' to need every one.
app.get('/api/orders/export', requireScope(['orders:read', 'orders:export'], 'all'), exportOrders)

// A role assigned to the person or one of their groups, not to everyone in the realm.
app.delete('/api/orders/:id', requireRole('orders-admin', { sources: ['user'] }), deleteOrder)

// A group (Group claim mapper) and a claim (any mapper, or the person's own claim).
app.get('/api/finance', requireGroup('finance'), requireClaim('department', 'finance'), report)

// A permission, and either a strong sign-in or the acme organization.
app.post(
  '/api/payouts',
  requireAuthio(requirePermission('payouts', 'create'), anyOf(requireAuthenticationLevel(2), requireOrganization('acme'))),
  payout,
)

import { AuthioForbiddenError, authorize, createAuthioVerifier, requirePermission } from '@hyper.authio/server'

const verifier = createAuthioVerifier({
  issuer: process.env.AUTHIO_ISSUER!,
  audiences: 'https://api.example.com',
})

export async function caller(authorization: string | undefined) {
  // Throws AuthioBearerError: answer 401 with error.wwwAuthenticate.
  const user = await verifier.verifyAuthorizationHeader(authorization)
  const refusal = authorize(user, requirePermission('orders', 'read'))

  // AuthioForbiddenError: answer 403, with error.wwwAuthenticate when it has one.
  if (refusal) throw new AuthioForbiddenError(refusal)

  return user
}

app.use(
  '/api',
  authioBearer({
    issuer: process.env.AUTHIO_ISSUER!,
    audiences: 'https://api.example.com',
    introspection: 'activeCheck',
    client: { clientId: process.env.AUTHIO_CLIENT_ID!, clientSecret: process.env.AUTHIO_CLIENT_SECRET },
  }),
)

import { createAuthioClient } from '@hyper.authio/client'

const authio = createAuthioClient({
  issuer: process.env.AUTHIO_ISSUER!,
  clientId: process.env.AUTHIO_CLIENT_ID!,
  clientSecret: process.env.AUTHIO_CLIENT_SECRET,
})

const ordersFetch = authio.clientCredentialsFetch({
  scopes: 'orders:read',
  resource: 'https://api.example.com',
})

const response = await ordersFetch('https://api.example.com/api/orders')

import { createAuthioClient } from '@hyper.authio/client'
import { createOnBehalfOf } from '@hyper.authio/server'

const billing = createOnBehalfOf({
  client: createAuthioClient({ issuer, clientId, clientSecret }),
  resource: 'https://billing.example.com',
  scopes: 'invoices:read',
})

app.get('/api/invoices', async (req, res) => {
  const response = await billing.fetch(req.authio!.user)('https://billing.example.com/invoices')
  res.status(response.status).json(await response.json())
})

import { authioWebhooks } from '@hyper.authio/express'

// Before express.json(): the signature is checked over the raw body.
app.post(
  '/webhooks/authio',
  authioWebhooks({ secret: process.env.AUTHIO_WEBHOOK_SECRET })
    .on('user_deleted', async (event) => forget(event.data.id))
    .on('*', (event) => console.log(event.type)),
)

import { FakeAuthio } from '@hyper.authio/testing'

const authio = await FakeAuthio.start({ realm: 'acme' })

const token = await authio.issueAccessToken({
  sub: 'u-1',
  audience: 'https://api.example.com',
  scope: 'orders:read',
  claims: { user_resource_access: { clerk: { orders: ['read'] } }, groups: ['finance'] },
})

// Point the API at authio.issuer, call it with the token, then:
await authio.close()