# specgit auth.md

You are an agent. This service supports **agentic registration** via the specgit GitHub App (fine-grained permissions, short-lived tokens): discover metadata → start sign-in → receive a session cookie → call the agent API. Follow the steps in order.

**Resource server:** `https://specgit.com/`  
**Authorization server:** `https://specgit.com/`

## Step 1 — Discover

Fetch Protected Resource Metadata and Authorization Server metadata.

### 1a. Protected Resource Metadata

```http
GET /.well-known/oauth-protected-resource
Host: specgit.com
```

Live URL: https://specgit.com/.well-known/oauth-protected-resource

Key fields: `resource`, `authorization_servers`, `scopes_supported`, `bearer_methods_supported` (use `Authorization: Bearer …` or session cookie after GitHub App sign-in).

### 1b. Authorization Server metadata

```http
GET /.well-known/oauth-authorization-server
Host: specgit.com
```

Live URL: https://specgit.com/.well-known/oauth-authorization-server

Read the `agent_auth` block: `skill`, `register_uri`, `claim_uri`, `revocation_uri`, and supported registration methods (`anonymous`, `identity_assertion`, `service_auth`).

## Step 2 — Register

specgit has no passwords and no separate credentials — a specgit account IS a GitHub identity (plus non-content preferences and terms acceptance stored server-side). All registration methods provision a GitHub-authenticated session cookie.

### identity_assertion — ID-JAG (preferred when available)

When your agent provider can mint an ID-JAG for the user, POST to the identity endpoint with `type: identity_assertion` and `assertion_type: urn:ietf:params:oauth:token-type:id-jag`. specgit verifies the assertion against provider JWKS, then issues a `session_cookie` credential.

### anonymous — session without prior identity

When no user identity is available upfront, use `type: anonymous` at the identity endpoint. specgit returns a pre-claim `session_cookie`; claim instructions are in this document (`claim_uri`).

### service_auth — GitHub App sign-in redirect

Start sign-in (browser or agent with redirect capability):

```http
GET /api/auth/app/login HTTP/1.1
Host: specgit.com
```

Live URL: https://specgit.com/api/auth/app/login

(The legacy `/api/auth/github/login` path redirects here.) The user authorizes the specgit GitHub App on GitHub — fine-grained permissions on only the repositories where the App is installed. On success, the callback at `https://specgit.com/api/auth/app/callback` sets an HttpOnly session cookie.

Verify session:

```http
GET /api/auth/session HTTP/1.1
Host: specgit.com
Cookie: <session-cookie>
```

Success response shape:

```json
{
  "user": { "id": "…", "displayName": "…", "avatarUrl": "…" },
  "connections": ["github"],
  "available": ["github"]
}
```

## Step 3 — Call the API

List agent tools:

```http
GET /api/agent/tools HTTP/1.1
Host: specgit.com
Cookie: <session-cookie>
```

Invoke a tool:

```http
POST /api/agent/invoke HTTP/1.1
Host: specgit.com
Content-Type: application/json
Cookie: <session-cookie>

{"tool": "read_document", "input": { … }}
```

OpenAPI: https://specgit.com/openapi.json

## Permissions

The specgit GitHub App uses fine-grained permissions on only the repositories
each installation grants — there are no broad OAuth scopes:

| Permission | Purpose |
|------------|---------|
| Contents (read & write) | Read and save documents in granted repositories |
| Pull requests (read & write) | Review branches, PRs, and comments |
| Profile (read) | Display name and avatar for collaboration presence |

## Credentials

| Type | Description |
|------|-------------|
| `session_cookie` | HttpOnly session cookie issued after the GitHub App sign-in callback |

## Pre-registration

No agent pre-registration is required. Any GitHub user with repository access may authenticate and use the agent API within their permitted repositories.

## Related discovery

- API catalog: https://specgit.com/.well-known/api-catalog
- MCP server card: https://specgit.com/.well-known/mcp/server-card.json
- Agent skills: https://specgit.com/.well-known/agent-skills/index.json
- LLM index: https://specgit.com/llms.txt
- Web Bot Auth JWKS: https://specgit.com/.well-known/http-message-signatures-directory

For access questions: security@fnfirst.com