# auth.md

You are an agent. This Vectoken public website supports Auth.md discovery for public resources. Browser users continue to use the normal website; agents should follow the registration flow below.

Resource server: https://www.vectoken.cn/

Authorization server metadata: https://www.vectoken.cn/.well-known/oauth-authorization-server

## agent_auth metadata

```json
{
  "agent_auth": {
    "skill": "https://www.vectoken.cn/auth.md",
    "identity_endpoint": "https://www.vectoken.cn/agent/identity",
    "claim_endpoint": "https://www.vectoken.cn/agent/identity/claim",
    "events_endpoint": "https://www.vectoken.cn/agent/events",
    "register_uri": "https://www.vectoken.cn/agent/identity",
    "claim_uri": "https://www.vectoken.cn/agent/identity/claim",
    "revocation_uri": "https://www.vectoken.cn/oauth2/revoke",
    "identity_types_supported": ["anonymous"],
    "credential_types_supported": ["identity_assertion"]
  }
}
```

## Step 1 - Discover

Fetch Protected Resource Metadata:

```http
GET /.well-known/oauth-protected-resource
Host: www.vectoken.cn
Accept: application/json
```

Then fetch Authorization Server Metadata:

```http
GET /.well-known/oauth-authorization-server
Host: www.vectoken.cn
Accept: application/json
```

## Step 2 - Pick a registration method

Use the anonymous registration method for public website resources.

```json
{
  "type": "anonymous",
  "scopes": ["public.read"]
}
```

Protected product APIs and customer model access require business onboarding. For those requests, contact `business@vectoken.com` with organization, agent identity, intended use, requested capability, expected volume, and contact email.

## Step 3 - Register

Register an anonymous agent identity:

```http
POST /agent/identity
Host: www.vectoken.cn
Content-Type: application/json
Accept: application/json

{
  "type": "anonymous",
  "scopes": ["public.read"]
}
```

Successful response:

```json
{
  "id": "vectoken-public-agent",
  "type": "anonymous",
  "scopes": ["public.read"],
  "identity_assertion": "vectoken-public-read",
  "token_endpoint": "https://www.vectoken.cn/oauth2/token",
  "claim_uri": "https://www.vectoken.cn/agent/identity/claim"
}
```

## Step 4 - Use credentials

Exchange the identity assertion for a public-read token response:

```http
POST /oauth2/token
Host: www.vectoken.cn
Content-Type: application/json
Accept: application/json

{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "vectoken-public-read",
  "scope": "public.read"
}
```

Successful response:

```json
{
  "access_token": "public-read",
  "token_type": "Bearer",
  "scope": "public.read"
}
```

Public resources:

- `/llms.txt`
- `/.well-known/api-catalog`
- `/.well-known/agent-skills/index.json`
- `/.well-known/mcp/server-card.json`
- `/sitemap.xml`

## Step 5 - Claim ceremony

Anonymous public-read access does not require ownership claim. If a claim flow is needed later, use:

```http
POST /agent/identity/claim
Host: www.vectoken.cn
Content-Type: application/json
Accept: application/json
```

## Step 6 - Revocation

Revoke the public-read assertion:

```http
POST /oauth2/revoke
Host: www.vectoken.cn
Content-Type: application/json
Accept: application/json

{
  "token": "public-read"
}
```

## Errors

| Error | Meaning | Agent action |
| --- | --- | --- |
| `invalid_request` | The request body is missing or malformed. | Retry with JSON and the fields shown above. |
| `unsupported_identity_type` | The requested identity type is not supported. | Use `anonymous` for public resources. |
| `insufficient_scope` | The requested scope is not available. | Use `public.read` or contact Vectoken for onboarding. |