# altsfor auth.md

> How an AI agent registers with altsfor.com and gets a credential for the MCP server at https://altsfor.com/mcp.

## Audience

Agents acting for a person who wants to search software alternatives, or list and launch a
software product. Reading is open; submitting needs a credential tied to a signed-in user.

## What you can do

| Scope | Tool | Access |
| --- | --- | --- |
| `mcp:read` | `search_apps` | no credential needed |
| `mcp:submit` | `submit_app` | bearer access token |

## Register (OAuth 2.1, dynamic client registration)

Public clients only: authorization code + PKCE (S256), no client secret.

1. Register a client:

```http
POST https://altsfor.com/oauth/register
Content-Type: application/json

{"client_name": "your-agent", "redirect_uris": ["https://your-agent.example/callback"]}
```

The response carries `client_id`. Save it; no client secret is issued.

2. Send the person's browser to `https://altsfor.com/oauth/authorize` with
   `response_type=code`, your `client_id`, an exact registered `redirect_uri`,
   `code_challenge` (base64url SHA-256 of a random `code_verifier`),
   `code_challenge_method=S256`, and `scope=mcp:read%20mcp:submit`.
   If nobody is signed in, altsfor asks them to sign in (Google or GitHub) and returns here.

3. Exchange the code:

```http
POST https://altsfor.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=...&code=...&redirect_uri=...&code_verifier=...
```

The JSON response has `access_token` (a signed JWT), `token_type: "Bearer"`,
`expires_in`, and `scope`.

4. Call the MCP server:

```http
POST https://altsfor.com/mcp
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_apps","arguments":{"query":"notion"}}}
```

## Alternative: MCP token

A signed-in person can mint a long-lived token at https://altsfor.com/submit#mcp and pass it the same
way. It is shown once; only a hash is stored.

## Credentials and revocation

- Access tokens are Ed25519-signed JWTs, valid for 365 days, sent in the `Authorization` header.
- Revoke with `POST https://altsfor.com/oauth/revoke` and `token=<access_token>`.
- Keys: https://altsfor.com/oauth/jwks
- Issuer: `https://altsfor.com`

## Discovery

- Authorization server metadata: https://altsfor.com/.well-known/oauth-authorization-server
- Protected resource metadata: https://altsfor.com/.well-known/oauth-protected-resource
- MCP server card: https://altsfor.com/.well-known/mcp/server-card.json
- Resource: `https://altsfor.com`, scopes: `mcp:read mcp:submit`

## Policies

- No anonymous writes. `submit_app` always acts as the signed-in user and accepts only
  the taxonomy ids in its input schema.
- Do not send credentials anywhere except https://altsfor.com.
- Questions: https://altsfor.com/llms.txt
