# auth.md

You are an agent. **ossium** supports agent registration discovery via this file and standard OAuth metadata. Follow the steps in order.

Audience: coding agents, MCP clients, and automations that help developers discover open source work, track contributions, or use Ossistant on behalf of a user.

## Hosts

| Role | URL |
|------|-----|
| Resource server (API + app) | `https://ossium.in` |
| Authorization / session | `https://ossium.in` (Better Auth social login) |
| This skill | `https://ossium.in/auth.md` |

## Step 1 — Discover

### 1a. Protected Resource Metadata (RFC 9728)

```http
GET https://ossium.in/.well-known/oauth-protected-resource
```

Expect JSON with:

- `resource` — `https://ossium.in`
- `authorization_servers` — `["https://ossium.in"]`
- `scopes_supported` — openid, profile, email, offline_access
- `bearer_methods_supported` — `["header"]`

On API 401 responses, look for:

```http
WWW-Authenticate: Bearer resource_metadata="https://ossium.in/.well-known/oauth-protected-resource"
```

### 1b. Authorization Server metadata (RFC 8414 + agent_auth)

```http
GET https://ossium.in/.well-known/oauth-authorization-server
```

Also available:

- OpenID Connect: `https://ossium.in/.well-known/openid-configuration`
- JWKS: `https://ossium.in/.well-known/jwks.json`
- API catalog: `https://ossium.in/.well-known/api-catalog`
- OpenAPI: `https://ossium.in/openapi.json`

Read the full `agent_auth` block. Important fields:

| Field | Purpose |
|-------|---------|
| `agent_auth.skill` | URL of this document |
| `agent_auth.register_uri` / `identity_endpoint` | Agent registration POST |
| `agent_auth.claim_uri` / `claim_endpoint` | Claim ceremony |
| `agent_auth.revocation_uri` | Revoke session / credentials |
| `agent_auth.identity_types_supported` | `anonymous`, `identity_assertion`, `service_auth` |
| `token_endpoint` | Session / token surface after auth |
| `authorization_endpoint` | Interactive human sign-in |

## Step 2 — Pick a method

1. **You can mint an ID-JAG** for this resource (`aud` = `https://ossium.in`) → `identity_assertion` + `urn:ietf:params:oauth:token-type:id-jag`.
2. **You only have the user's email** → `service_auth` (claim ceremony via verified email).
3. **Neither** → `anonymous` (limited scopes until claim).

Also supported for humans (not agent registration POST): sign in at `https://ossium.in/auth` with **Google** or **GitHub** (Better Auth). Session cookie: `better-auth.session_token`.

## Step 3 — Register

Surface `resource_name` (**ossium**) and scopes to the user before asserting identity (skip for pure anonymous).

### identity_assertion + ID-JAG

```http
POST https://ossium.in/agent/identity
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<ID-JAG JWT>"
}
```

### service_auth (verified email)

```http
POST https://ossium.in/agent/identity
Content-Type: application/json

{
  "type": "service_auth",
  "login_hint": "user@example.com"
}
```

### anonymous

```http
POST https://ossium.in/agent/identity
Content-Type: application/json

{ "type": "anonymous" }
```

If registration returns `anonymous_not_enabled`, `service_auth_not_enabled`, or `issuer_not_enabled`, fall back to interactive sign-in at `https://ossium.in/auth` and use the session cookie for protected APIs.

## Step 4 — Claim (when required)

```http
POST https://ossium.in/agent/identity/claim
Content-Type: application/json

{
  "claim_token": "clm_...",
  "email": "user@example.com"
}
```

Surface `verification_uri` and `user_code` to the user. User completes claim in the browser (sign in at `https://ossium.in/auth` if needed).

Poll token exchange with grant `urn:workos:agent-auth:grant-type:claim` when the AS advertises it.

## Step 5 — Use credentials

### Session cookie (current production path)

After the user completes Google/GitHub sign-in at `https://ossium.in/auth`:

1. Call `https://ossium.in/api/auth/get-session` to confirm the session.
2. Call protected APIs with the same cookie jar.
3. Prefer public discovery APIs when login is unnecessary (trending, GSoC, issues listings — see OpenAPI).

### Bearer access_token (agent registration path)

When registration succeeds and a bearer token is issued:

```http
GET https://ossium.in/api/...
Authorization: Bearer <access_token>
```

## Public vs protected

Many listing endpoints work **without** auth (see `https://ossium.in/openapi.json` and `https://ossium.in/.well-known/api-catalog`). Protected routes (dashboard writes, user settings, premium, Ossistant history) require a signed-in user session.

## Revocation

- Session: `https://ossium.in/api/auth/sign-out` (`revocation_uri` / `end_session_endpoint`)
- Provider-driven assertion revoke events: `agent_auth.events_endpoint` = `https://ossium.in/agent/event/notify`
- Event type: `https://schemas.workos.com/events/agent/auth/identity/assertion/revoked`

## Product links

- Home / discovery: https://ossium.in/home
- Ossistant: https://ossium.in/chat
- About: https://ossium.in/about
- Privacy: https://ossium.in/privacy
- Terms: https://ossium.in/terms
- Contact: help@ossium.in · https://ossium.in/contact

## Safety

- Do **not** ask users to paste passwords or long-lived API keys into chat.
- Prefer environment / secret stores for any out-of-band credentials.
- Never log session cookies or bearer tokens.
- Respect rate limits (`429` + `Retry-After`).

## Errors (registration)

| Code | Meaning |
|------|---------|
| `anonymous_not_enabled` | Use another method or interactive /auth |
| `service_auth_not_enabled` | Use another method |
| `issuer_not_enabled` | Provider not on trust list |
| `invalid_request` | Fix body / assertion |
| `interaction_required` | User must claim / confirm |
| `login_required` | Re-auth at agent provider, mint fresh ID-JAG |

---

Last updated: 2026-07-16 · Protocol: [auth.md](https://github.com/workos/auth.md) · Site: https://ossium.in