Mint an Identity
Two ways to get a routable address: a new principal with a key of its own, or one more on the key you hold.
Mint an Identity Documentation
Two operations allocate an address. register creates a new principal and returns a key for it. identity allocates another address on the key that made the call.
register
Allocates a /128, publishes its DNS, pins its key, writes its registry record, and returns a key belonging to the new agent. Needs admin:dns.
CALL whisper.agents({op: 'register', args: {contact_email: 'ops@example.com', label: 'checkout-bot'}})
Arguments
| Argument | Contract |
|---|---|
label | Required. The short name the agent is known by. |
contact_email | Optional. Published on the public registry record for the address. |
whale | Optional map. {v: 1, publish_name: false} declines the guessable short alias. Fleet use is on Nodes, names and tags. |
Returns
| Column | Holds |
|---|---|
agent | The agent identifier. |
address | The routable IPv6 /128 it now holds. |
fqdn | Its canonical name. |
ptr | The reverse name that resolves back to it. |
doh_url | Its encrypted-DNS URL, with a token in the path. |
resolver_ip | The account's dedicated resolver address. |
member | The short alias, when one was published. |
member_published | Whether the alias was published. Read this rather than testing member for emptiness. |
api_key | The new agent's own key. |
api_key and doh_url appear on this one answer and never again. Capture both, and treat the doh_url as a password. The name in fqdn is a function of the address, derived as The address as identity sets out.
identity
Allocates another address on the calling key, or hands one back. Needs dns:identity.
CALL whisper.agents({op: 'identity', args: {label: 'reporting-job'}})
To hand one back, name the address and set release.
CALL whisper.agents({op: 'identity', args: {address: '2a04:2a01:b69a:6717:e3b0:51ff:3bf7:f478', release: true}})
Arguments
| Argument | Contract |
|---|---|
label | The short name for the new address. |
contact_email | Optional. Published on the registry record. |
release | true releases an address instead of allocating one. |
address | The address to release. Required with release. |
Returns
| Column | Holds |
|---|---|
address | The /128 allocated or released. |
fqdn | Its canonical name. |
ptr | Its reverse name. |
state | Where the allocation now stands. |
doh_url | The encrypted-DNS URL for it. |
resolver_ip | The account's dedicated resolver address. |
No second key comes back, because the address answers on the key that asked for it.
Which one to use
Use register when the thing being minted holds its own credential and should be governed as a principal in its own right. Use identity when one caller runs several addresses under the key it already has. On the command line the difference is whisper create --register --name <name> against whisper create --name <name>, and Create an identity walks the first one through.
Errors
| Code | Status | Meaning |
|---|---|---|
BAD_ARGS | 400 | A required argument is missing, or one is the wrong shape. |
RESERVED_NAME, OFFENSIVE_NAME, PREMIUM_NAME | 403 | The label is not available under the naming rules. Pick another. |
REGISTER_IN_PROGRESS | 409 | A register for this account is already running. Wait for it to finish. |
AGENT_LIMIT, IDENTITY_LIMIT | 429 | The account's allowance is used up. Sign in to see the account, or ask Whisper to widen it. |
PUBLISH_FAILED, STORE_UNAVAILABLE | 503 | The allocation did not reach DNS. Retry after the interval in retry_after. |