# auth.md

How an autonomous agent or other automated client authenticates against the
Every Yarn API. This document is the authoritative description.

## Discovery

There is no OAuth discovery metadata to read instead of this document.

## Audience

Agents and server-side integrations reading catalog data. Tokens identify a
calling application, not an end user, and carry no user context: there is no
delegated or on-behalf-of flow.

## Supported methods

| Method | Supported | Notes |
| --- | --- | --- |
| Operator-issued bearer token | yes | The only way to call this API. |
| OAuth 2.0 client credentials | no | No authorization server runs here: no token endpoint is offered, and any published RFC 8414 document exists only to advertise the `agent_auth` registration block. |
| Dynamic client registration (RFC 7591) | no | Registration is reviewed by a human. |
| Anonymous or unauthenticated access | no | Every route under `/api/v1/external` requires a token. |

## Registration

Registration endpoint: `mailto:support@everyyarn.com`

Provisioning is operator-reviewed, not automated: there is no HTTP registration
endpoint and no self-serve token issuance. Send a registration request to the
address above containing:

- `client_name`: the name of the application or agent
- `organization`: who operates it
- `scopes`: the scopes it needs, from the list below
- `contact_email`: where the credential and any revocation notice should be sent
- `expected_volume`: requests per minute at steady state

A token is returned to `contact_email`, or the request is refused with a reason.
An agent that cannot complete an out-of-band registration cannot use this API.

## Using a token

Send the token as a bearer credential on every request:

```http
GET https://www.everyyarn.com/api/v1/external/yarns
Authorization: Bearer <token>
Accept: application/json
```

Requests without a valid token receive `401`. Requests with a valid token that
lacks the scope required by the route receive `403`.

## Scopes

A token carries an explicit scope list. Scopes granted today:

| Scope | Grants |
| --- | --- |
| `assessments:read` | Read assessment data |
| `assessments:write` | Create and update assessments |
| `yarns:read` | Read yarn catalog data |
| `brands:read` | Read brand data |
| `fiber-weights:read` | Read fiber weight classifications |
| `fiber-materials:read` | Read fiber material data |
| `imports:write` | Submit YarnSaver import batches |
| `valuations:read` | Read yarn valuation ranges and price bands |
| `reference:read` | Read reference lists such as delivery and payout methods |
| `products:read` | Read storefront product records |
| `orders:read` | Read storefront orders |
| `orders:write` | Pick and ship storefront orders |
| `reports:read` | Read staff reports across every customer |
| `customers:act-as` | Act on behalf of a customer identified by X-Customer-Email |
| `destash:storefronts:read` | Read marketplace storefronts |
| `destash:storefronts:write` | Create and update marketplace storefronts |
| `destash:listings:read` | Read marketplace listings |
| `destash:listings:write` | Create and update marketplace listings |
| `destash:orders:read` | Read marketplace orders for a seller |
| `destash:orders:write` | Buy labels and mark marketplace orders shipped |
| `destash:payouts:read` | Read marketplace payout balances |

## Rate limits

Tokens default to 60 requests per minute. Per-token and per-account
overrides are available on request. Exceeding the limit returns `429`.

## Revocation

Revocation endpoint: `mailto:support@everyyarn.com`

Tokens may carry an expiry date and are revoked by the operator. To report a
compromised token or retire one you no longer need, write to that address. A
revoked token stops authenticating immediately.

## agent_auth

Machine-readable registration metadata. The same block is advertised in the
OAuth authorization server metadata when that document is published.

```json
{
    "skill": "https://www.everyyarn.com/auth.md",
    "identity_types_supported": [
        "anonymous"
    ],
    "anonymous": {
        "credential_types_supported": [
            "api_key"
        ]
    },
    "register_uri": "mailto:support@everyyarn.com",
    "revocation_uri": "mailto:support@everyyarn.com"
}
```

## Machine-readable descriptions

- [/openapi.json](/openapi.json): OpenAPI 3.1 description of every route and its scope
- [/.well-known/api-catalog](/.well-known/api-catalog): RFC 9727 linkset of API documents
- [/llms.txt](/llms.txt): site overview