# Authos Backend Integration

> Secure backend APIs with AuthOS-issued JWTs and the AuthOS Node server adapter. Use when building an API that must verify AuthOS bearer tokens, enforce JWT claims, add Express middleware, validate JWKS keys, or create a backend-owned session after a browser OAuth callback.

- **Type:** Skill
- **Install:** `agentstack add skill-drmhse-authos-skill-authos-backend-integration`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [drmhse](https://agentstack.voostack.com/s/drmhse)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [drmhse](https://github.com/drmhse)
- **Source:** https://github.com/drmhse/authos_skill/tree/master/authos-backend-integration
- **Website:** https://authos.dev/docs/ai-agent-skills/

## Install

```sh
agentstack add skill-drmhse-authos-skill-authos-backend-integration
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
npm install @drmhse/authos-node
```

Verify a token directly:

```typescript
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;
```

For Express, import middleware from the package subpath:

```typescript
import { createAuthMiddleware } from '@drmhse/authos-node/express';

const { requireAuth, requirePlatformOwner, requireAnyPermission } =
  createAuthMiddleware({ baseURL: process.env.AUTHOS_BASE_URL! });

app.get('/api/me', requireAuth(), (req, res) => {
  res.json({ user: req.auth!.claims.sub });
});

app.get(
  '/api/admin',
  requireAuth(),
  requirePlatformOwner(),
  (_req, res) => res.json({ ok: true })
);

app.post(
  '/api/billing',
  requireAuth(),
  requireAnyPermission(['billing.manage']),
  (_req, res) => res.json({ ok: true })
);
```

## Manual Verification

For non-Node backends:

1. Extract `Authorization: Bearer `.
2. Decode the JWT header without trusting claims yet.
3. Require `alg = RS256` and a present `kid`.
4. Fetch and cache `/.well-known/jwks.json`.
5. Select the RSA JWK by `kid`.
6. Verify the signature, `exp`, optional `iss`, optional `aud`, and then enforce app authorization.

Do not verify AuthOS access tokens with a shared secret. Do not use the private signing key in applications. Do not accept unsigned or HS256 tokens.

## Common Pitfalls

- Do not send callback fragments to the backend by expecting `?access_token=...`; fragments are client-side only.
- Do not assume all tokens are org-scoped. Platform-owner and platform-level sessions may lack `org_slug` or `service_slug`.
- Do not use service API keys as user JWTs. API keys belong to `X-Api-Key` service API routes.
- If the backend relies on roles, fetch explicit permissions when needed instead of assuming legacy strings like `org:manage` cover every capability.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [drmhse](https://github.com/drmhse)
- **Source:** [drmhse/authos_skill](https://github.com/drmhse/authos_skill)
- **License:** MIT
- **Homepage:** https://authos.dev/docs/ai-agent-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-drmhse-authos-skill-authos-backend-integration
- Seller: https://agentstack.voostack.com/s/drmhse
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.