RSL licences for your agent

Get an RSL licence token with a capped agent token, read with it, and what each refusal asks you to do.

On this page

What a licence is here
Getting a token
Reading with it
When a read is refused
Binding a token to your key

A site tolled by naulon publishes its terms as an RSL document at /license.xml. An RSL client can read those terms, ask a licence server for a licence, and present it on every request instead of paying each 402 itself. naulon runs that licence server for every site it hosts. This page is for you if you run such a client and already have an agent token.

What a licence is here

A licence token is a standing authorization, not a prepaid pass. Nothing is paid when you get one. Each read you make with it is charged separately, from your own balance, to that page's authors, at the price the site published when the token was issued. Your agent token's lifetime cap bounds the total, exactly as it does when your agent pays a 402.

That is why a licence needs a capped agent token. A token with no cap can still pay 402s, but /token refuses it: a licence charges without asking, so it has to have a ceiling. Set one at /buyer/agents.

Getting a token

Post the <license> element you want, copied from the site's /license.xml, with your agent token as HTTP Basic credentials. The client_id is the token's id (shown on /buyer/agents), and the client_secret is the token itself.

curl -s https://example.com/_naulon/olp/token \
  -u "3f2c9a4e-8b1d-4c7e-9f00-2a6b1c5d7e81:nln_agent_…" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode resource='https://example.com/essays/*' \
  --data-urlencode license='<license><permits type="usage">ai-input ai-index</permits><payment type="crawl"><amount currency="USD">0.001</amount></payment></license>'

{ "access_token": "olp_Qm9…", "token_type": "License", "expires_in": 86400 }

resource is the <content url> the licence sits under, or any URL inside it. The site publishes two priced licences per section, and which one you post is your choice:

crawl is a read. Your agent reads the page and answers with it.
use is a citation. It costs the site's citation price, which may equal the read price. Send those reads as citations (x-naulon-kind: citation).

When a site names naulon as its licence server, RSL asks for a licence even for its free terms, such as search. Post that free licence the same way. It is issued without a cap or a balance, and it never charges, but it also never pays for a priced read.

The licence you post is matched against the published one by meaning: the same payment type, amount, currency and permitted uses. A licence that asks for something the site did not offer, such as ai-train, is refused as invalid_license.

A token lives for at most a day, and never longer than the agent token behind it. Revoking the agent token kills every licence it got.

Reading with it

curl -s https://example.com/essays/on-stillness -H "Authorization: License olp_Qm9…"

The read is charged and served in one request, and it leaves the same permanent citation record a paid 402 does. That record says it was charged under a standing licence, and what witnessed the read. Reading the same page again while the first read's re-read window is open costs nothing: the response says agent reread (licence).

When a read is refused

Every refusal is JSON with an error and an error_description, and each one asks for something different:

`error`	Status	What to do
`invalid_token`	401	Get a new token. It expired, was never issued for this site, or its agent token was revoked.
`out_of_scope`	403	The URL is outside the section the token was issued for. Get a token for it.
`price_scope`	403	A narrower section inside yours has its own price. Get a token for that section.
`price_rose`	402	The site raised its price after you got the token. Get a new one, or pay this read over x402: the 402 carries the usual `PAYMENT-REQUIRED` header.
`payment_refused`	402	Your balance or your cap refused the charge. The description says which.
`signature_required`	401	Sign the request with the key the token is bound to (below). On a site that serves its own pages, only a signed read can be charged, so a token you got without signing `/token` cannot be used there.
`licence_insufficient`	402	A free licence does not pay for a priced read. Get a `crawl` licence, or pay this read over x402.
`wrong_licence_kind`	403	A `crawl` licence pays for reads and a `use` licence for citations. Send the read as the kind your licence is for.
`replayed`	403	That signed request was already used. Sign a fresh one.
`cap_required`	403	Your agent token lost its cap. Set one again.
`in_flight`	503	A charge for this URL is already running. Retry after the `retry-after` seconds.
`licence_server_unavailable`	503	The licence could not be checked. Retry, or pay this read over x402 meanwhile.

Binding a token to your key

If your client signs its requests with Web Bot Auth, sign the /token request too. The token is then bound to that key, and a read is only charged when it carries a signature from the same key covering @authority and @path, valid for no more than 300 seconds. A bound token presented without that signature is refused, so a leaked token alone reads nothing. Its records name your signature as the witness instead of the gate.

On a site whose own server delivers its pages, naulon never sees the read, so your signature is the only proof it happened. There, a licence is charged only for a signed request, and each signature is charged at most once.