primitive docs
primitive app

Agent Authorization

Authentication standards — SPF, DKIM, DMARC — answer "is this message really from the domain it claims?" None of them answer "does the recipient want contact from an autonomous agent, and from which ones?"

Agent Authorization is that signal: one public DNS TXT record you publish at _agents on your own domain. It is the mirror image of SPF — SPF authorizes servers to send as your domain; this authorizes agents to make contact with it. Control of your DNS proves the opt-in is intentional, since only the domain owner can publish the record.

This is a draft, vendor-neutral standard (version AGENTS1). The full grammar, trust model, and evaluation rules are published at primitive.dev/specs/agent-authorization (raw markdown at /specs/agent-authorization/raw). This page is the practical guide.

Opt in

To let agents on Primitive email your domain, publish a single TXT record at _agents on your domain:

_agents.example.com.  IN  TXT  "v=AGENTS1; p=accept; channel=email; allow=provider:primitive.dev"

That's the whole opt-in. No record means no permission, and you can change or remove it at any time.

The record

The value is a set of key=value tags separated by ;:

TagMeaning
vFormat version. v=AGENTS1 today. Required.
pPolicy. p=accept opts in. Anything else (or no accept) is treated as not opted in.
channelThe channel this record authorizes. email is the first defined channel.
allowWho may contact you on this channel (see below). Required under p=accept.

allow tokens

allow is a space- or comma-separated list of principals. A sender is authorized if it matches any token:

TokenAuthorizes
provider:primitive.devAny agent hosted on Primitive.
domain:sender.exampleA specific sending From-domain, regardless of provider.
*Any compliant agent on this channel.

For example, to accept Primitive-hosted agents and one partner's own domain:

_agents.example.com.  IN  TXT  "v=AGENTS1; p=accept; channel=email; allow=provider:primitive.dev domain:partner.dev"

An explicit empty allow= is deny-all (it matches nothing).

How it is evaluated

When a Primitive-hosted agent tries to email your domain, Primitive resolves _agents.<your-domain> and applies the standard:

  • It queries TXT at the exact name _agents.<domain> (not a subtree).
  • It reads only AGENTS1 records; unknown versions and unknown ordinary tags are ignored. An unknown critical tag (prefixed !) fails closed.
  • The match must be for the email channel and the contacting agent must match an allow token.

The evaluation fails closed: a missing record, more than one conflicting record, a malformed record, or a DNS lookup that can't be resolved (SERVFAIL/timeout) all resolve to not authorized. An inconclusive lookup is transient — the send may be retried.

Relationship to sending

Agent Authorization is the recipient side of consent. The matching sender-side capability is the send_to_opted_in_domains gate: it lets a Primitive org send to addresses on domains that have opted in via their _agents record, even when the org does not own that domain. See Sending Mail for the full gate model. That gate is enabled per organization; if it is off, an opted-in recipient still won't unblock sends.

Related Pages