# Kevytyrittäjälaskuri auth.md

You are an agent. This service supports **agentic registration**: discover → register → (claim if needed) → exchange for an access token → call API → handle revocation. Follow the steps in order; do not skip ahead.

This guide provides registration and authentication procedures for autonomous AI agents, crawlers, and automated clients interacting with Kevytyrittäjälaskuri.fi computation services and APIs.

## Agent Audience

This document is intended for autonomous AI agents, automated client applications, and background crawlers wishing to interact programmatically with Kevytyrittäjälaskuri.fi APIs and computation services.

## Step 1 — Discover

Kevytyrittäjälaskuri publishes standard RFC discovery documents:

- **OAuth Protected Resource Metadata (RFC 9728):** https://kevytyrittaja-laskuri.fi/.well-known/oauth-protected-resource
- **OAuth Authorization Server Metadata (RFC 8414):** https://kevytyrittaja-laskuri.fi/.well-known/oauth-authorization-server
- **OpenID Connect Discovery:** https://kevytyrittaja-laskuri.fi/.well-known/openid-configuration
- **API Catalog (RFC 9727):** https://kevytyrittaja-laskuri.fi/.well-known/api-catalog
- **MCP Server Card:** https://kevytyrittaja-laskuri.fi/.well-known/mcp/server-card.json
- **Agent Skills Discovery:** https://kevytyrittaja-laskuri.fi/.well-known/agent-skills/index.json
- **ARD Capability Manifest:** https://kevytyrittaja-laskuri.fi/.well-known/ai-catalog.json

### 1a. Protected Resource Metadata
- Resource Identifier: https://kevytyrittaja-laskuri.fi
- Authorization Server: https://kevytyrittaja-laskuri.fi
- Scopes: read, calculate, agent
- Bearer Methods: header

### 1b. Authorization Server Metadata
- Issuer: https://kevytyrittaja-laskuri.fi
- Token Endpoint: https://kevytyrittaja-laskuri.fi/oauth/token
- Revocation Endpoint: https://kevytyrittaja-laskuri.fi/agent/revoke
- Registration Endpoint: https://kevytyrittaja-laskuri.fi/agent/register
- Claim Endpoint: https://kevytyrittaja-laskuri.fi/agent/claim

## Supported Registration Methods & Identity Types

This service supports multiple registration and provisioning flows:
- **Anonymous:** Unauthenticated agents obtain read/calculate credentials.
- **Identity Assertion (ID-JAG):** Authenticated agents with an OIDC token-exchange assertion (`urn:ietf:params:oauth:token-type:id-jag`).
- **Verified Email:** Agents with domain or email ownership verified via claim ceremony.

## Registration Endpoints

- **Registration / Provisioning Endpoint:** https://kevytyrittaja-laskuri.fi/agent/register
- **Claim Endpoint:** https://kevytyrittaja-laskuri.fi/agent/claim
- **Token Endpoint:** https://kevytyrittaja-laskuri.fi/oauth/token
- **Revocation Endpoint:** https://kevytyrittaja-laskuri.fi/agent/revoke

## Step 2 — Pick a Registration Method

Select the appropriate identity flow based on available credentials:

1. **Anonymous Access:** Suitable for public calculations, comparison data, and read operations without persistent user binding.
2. **Identity Assertion (ID-JAG):** For agents carrying an OIDC ID-JAG token (`urn:ietf:params:oauth:token-type:id-jag`) minted by an authorized agent provider.
3. **Verified Email:** For agents with user-delegated domain or email assertion. Requires claim verification ceremony.

## Step 3 — Register

Send a registration request to the registration endpoint:

```http
POST /agent/register HTTP/1.1
Host: kevytyrittaja-laskuri.fi
Content-Type: application/json

{
  "identity_type": "anonymous",
  "client_name": "MySalaryAgent/1.0",
  "scopes": ["read", "calculate"]
}
```

Or with an Identity Assertion (ID-JAG):

```http
POST /agent/register HTTP/1.1
Host: kevytyrittaja-laskuri.fi
Content-Type: application/json

{
  "identity_type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "eyJhbGciOiJSUzI1NiIs...",
  "scopes": ["read", "calculate", "agent"]
}
```

Response shape (HTTP 200 / 201):

```json
{
  "status": "registered",
  "agent_id": "agent_anon_9283f4",
  "credential_type": "api_key",
  "api_key": "kvr_live_anon_mock_key_2026",
  "claim_uri": "https://kevytyrittaja-laskuri.fi/agent/claim?id=agent_anon_9283f4",
  "expires_in": 86400
}
```

## Step 4 — Claim Ceremony (When Required)

For anonymous sessions wishing to bind to a verified owner, or email-verified flows:

```http
POST /agent/claim HTTP/1.1
Host: kevytyrittaja-laskuri.fi
Content-Type: application/json

{
  "agent_id": "agent_anon_9283f4",
  "verification_code": "482-910"
}
```

## Step 5 — Exchange Token

If exchanging an identity assertion or service authorization grant for an OAuth 2.0 access token:

```http
POST /oauth/token HTTP/1.1
Host: kevytyrittaja-laskuri.fi
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&subject_token=eyJhbGciOiJ...
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid-jag
&scope=read+calculate
```

Response (HTTP 200):

```json
{
  "access_token": "kvr_at_89123847a19c",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read calculate"
}
```

## Step 6 — Credential Usage

Include your issued bearer token in the HTTP `Authorization` header on all protected API requests:

```http
GET /api/calculate HTTP/1.1
Host: kevytyrittaja-laskuri.fi
Authorization: Bearer YOUR_AGENT_TOKEN
Accept: application/json
```

### Supported API Scopes:
- `read`: Read salary limits, tax rates, and invoicing service comparison data.
- `calculate`: Compute net income, YEL obligations, and service fees.
- `agent`: Access agent-specific skills, WebMCP tools, and MCP server endpoints.

## Step 7 — Handle Revocation

When an agent session terminates or credentials are compromised, notify the revocation endpoint:

```http
POST /agent/revoke HTTP/1.1
Host: kevytyrittaja-laskuri.fi
Content-Type: application/json

{
  "token": "YOUR_AGENT_TOKEN",
  "reason": "agent_decommissioned"
}
```

Response: HTTP 200 `{"status": "revoked"}`