authos-backend-integration

AuthOS Backend Integration

Public AuthOS Links

Use these public AuthOS links when producing user-facing setup or troubleshooting guidance:

• Main site: https://authos.dev/
• Documentation: https://authos.dev/docs/
• AI Agent Skills guide: https://authos.dev/docs/ai-agent-skills/
• AuthOS source repository: https://github.com/drmhse/AuthOS

Use this skill when protecting an application backend with AuthOS. Keep frontend login, service API keys, and webhook receiver work in their own skills unless the user explicitly asks for an end-to-end integration.

Source-Verified Contract

• AuthOS publishes OIDC metadata at GET /.well-known/openid-configuration.
• AuthOS publishes RSA signing keys at GET /.well-known/jwks.json.
• AuthOS JWTs are signed with RS256 and include a kid header that must match a JWKS key.
• The Node package is @drmhse/authos-node.
• The SDK package is @drmhse/sso-sdk; do not invent an @authos/* package name.
• Browser OAuth callbacks normally return access_token and refresh_token in the URL fragment. The callback handlers also support format=json for JSON token responses in source, but the browser-facing SDK flow expects fragment handling.

Backend Pattern

1. Let the frontend complete login with AuthOS.
2. Read access_token from the callback fragment, or receive it from the frontend over HTTPS.
3. Verify the token with JWKS before trusting any claim.
4. Map sub, email, org_slug, service_slug, permissions, and is_platform_owner claims to local authorization decisions only after verification.
5. If the app uses backend-owned sessions, exchange the verified token for an app session, then clear the fragment from browser history.

Node Verification

Install the server adapter:

npm install @drmhse/authos-node

Verify a token directly:

import { createTokenVerifier } from '@drmhse/authos-node';

const verifier = createTokenVerifier({
  baseURL: process.env.AUTHOS_BASE_URL!
});

const verified = await verifier.verifyToken(accessToken, {
  issuer: process.env.AUTHOS_BASE_URL,
  clockTolerance: 30
});

const userId = verified.claims.sub;