# auth.md

You are an agent. NOTALONE Studio (定然數位公關行銷) supports **agentic registration** for its public consultation and site APIs: discover → register → (claim if needed) → exchange for an access_token → call API.

Service hosts:

- Resource / site: `https://notalonestudio.com`
- Authorization server: `https://notalonestudio.com` (same origin)

Audience: agents acting for marketers, founders, or partners who want to book a consultation or read public company information programmatically.

## Step 1 — Discover

### 1a. Protected Resource Metadata

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

### 1b. Authorization Server metadata

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

The `agent_auth` block lists `register_uri`, supported identity types, and claim endpoints.

## Step 2 — Register

Preferred method for this site: **verified email** claim ceremony.

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

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

Also supported:

- `identity_assertion` with `urn:ietf:params:oauth:token-type:id-jag`
- `anonymous` (pre-claim, limited scopes)

Human fallback: email `saralin1201@notalonestudio.com` with subject `Agent registration` and your agent callback URL.

## Step 3 — Claim (when required)

Open `verification_uri` from the registration response, enter the `user_code`, then poll the token endpoint with the claim grant.

## Step 4 — Exchange

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

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

## Step 5 — Call APIs

Send `Authorization: Bearer <access_token>` to:

- `GET /api/health`
- `GET /api/openapi.json`
- `POST /api/consultation` (scope `consultation.write`)

## Scopes

| Scope | Purpose |
| --- | --- |
| `site.read` | Read public company and service metadata |
| `consultation.write` | Submit a consultation request on behalf of a user |

## Revocation

Agents SHOULD honor revocation events from `POST /agent/event/notify` and stop using revoked credentials.