# auth.md

You are an agent. ToolJiffy supports **agentic registration**: discover → register → use. All 310+ browser-based developer, text, image, PDF, video, and measurement utilities are available for public anonymous invocation. Follow the steps below to authenticate or register.

## Step 1 — Discover

Discovery is two hops.

### 1a. Fetch the Protected Resource Metadata

```http
GET https://tooljiffy.com/.well-known/oauth-protected-resource
```

Response:

```json
{
  "resource": "https://tooljiffy.com",
  "authorization_servers": ["https://tooljiffy.com"],
  "scopes_supported": ["tools:read", "tools:execute"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://tooljiffy.com/auth.md"
}
```

- `resource` — canonical URL of the ToolJiffy service.
- `authorization_servers` — base URL of the authorization server (same origin).
- `scopes_supported` — `tools:read` (list/describe tools), `tools:execute` (invoke tools).
- `bearer_methods_supported` — send tokens via `Authorization: Bearer …` header.

### 1b. Fetch the Authorization Server Metadata

```http
GET https://tooljiffy.com/.well-known/oauth-authorization-server
```

The response includes the `agent_auth` block with endpoints and supported identity types (see below).

## Step 2 — Pick a method

Use this decision tree:

1. **You have a user identity and can mint an ID-JAG** → `identity_assertion` (fastest, no human in the loop).
2. **You have only the user's verified email** → `service_auth`. Claim ceremony required.
3. **You have neither** → `anonymous`. No registration required for public tools.

## Step 3 — Register

### identity_assertion + id-jag

POST to the `identity_endpoint` with an audience-bound ID-JAG:

```http
POST https://tooljiffy.com/agent/identity
Content-Type: application/json

{
  "identity_type": "identity_assertion",
  "assertion": "<id-jag-jwt>",
  "scope": "tools:read tools:execute"
}
```

### anonymous

All ToolJiffy browser tools support public anonymous invocation (`auth_required: false`). No registration is needed. Agents may invoke any tool directly via the MCP Server or WebMCP interface.

For rate-limit bypass or persistent sessions, register anonymously:

```http
POST https://tooljiffy.com/agent/identity
Content-Type: application/json

{
  "identity_type": "anonymous",
  "scope": "tools:read tools:execute"
}
```

Then optionally claim via `claim_endpoint`.

## Step 4 — Exchange for access_token

Exchange the service-signed identity assertion at the token endpoint:

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

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=<service-signed-identity-assertion>
```

## Step 5 — Call API

Include the access token in API requests:

```http
GET https://tooljiffy.com/api/tools
Authorization: Bearer <access_token>
```

## Additional Resources

- **MCP Server Card**: `https://tooljiffy.com/.well-known/mcp/server-card.json`
- **Agent Skills Index**: `https://tooljiffy.com/.well-known/agent-skills/index.json`
- **API Catalog**: `https://tooljiffy.com/.well-known/api-catalog`
- **Privacy Policy**: `https://tooljiffy.com/privacy-policy/`
- **Terms & Conditions**: `https://tooljiffy.com/terms-and-conditions/`