Registry API

GET/v1/health

Auth

None.

Answer

{ "ok": true, "service": "registry-api", "environment": "production" }

GET/v1/config

Auth

None.

Answer

{ siteOrigin, apiOrigin, filesOrigin, pnsOrigins[], turnstileSiteKey, stripeMode, term, root, devLogin }. term is { months, renewalMode }, the registration term (12 months, renewed yearly, by default). stripeMode is test or live; root is { kid, publicKey, x }, or null if the root key is not configured; devLogin is true only on a development registry.

GET/v1/root-key

Auth

None.

Answer

{ kid, publicKey: { kty: "OKP", crv: "Ed25519", x }, algorithm: "Ed25519" }, cacheable for an hour. The same as a PNS server’s /root-key.

Errors

503 config_error, “The registry signing key is not configured.”

GET/v1/namespaces

Auth

None.

Answer

{ namespaces: [...] }, all 17 in family order, cacheable for a minute. Each is { tld, family, scheme, defaultDirection, verificationLevel, verificationLabel, offered, priceCents, required, requiredTxtKinds, ownerSupplied, persona, transferable, relationshipLabels, example, whoMayRegister, rules }. offered, priceCents (the yearly fee in cents: 0 for .avatar, 100000 for .realm), verificationLevel and rules are live settings an administrator can change, and the registry enforces the level that is set. See Namespaces.

GET/v1/namespaces/:tld

Auth

None.

Answer

One namespace, as above. A leading dot is allowed: /v1/namespaces/.character.

Errors

404 not_found, “.example is not a Mesh namespace.”

GET/v1/search?q=oasis

Auth

None. Signed in, the answer is the one the caller would get on registering: a holder of a reservation sees that name as available (except where review is required anyway: a tragedy, or any .figure), and the verified owner of a matching web domain sees its priority.

Answer

{ query, label, valid, message?, results[], suggestions[] }. q may be oasis, oasis.character or activate://oasis.character; its first label is checked. An invalid label still answers 200, with valid: false, the reason in message, and no results.

Errors

429 rate_limited, “Too many searches at once. Please wait a moment and try again.”

results has one row per namespace, 17 in family order: { tld, family, name, address, state, priceCents, verificationLevel, ownerLabel?, reason?, reservedReason?, requestable?, priorityDomain?, heldByYou? }. Each row’s priceCents is that namespace’s yearly fee, and its address carries the locked scheme: activate://, portal:// or experience://. For a reserved name, reservedReason says why it is held and requestable whether it may be requested (the request goes to review). Two fields appear only for a signed-in caller: heldByYou: true when the reservation is the caller’s (held for the account, or for a domain it has proved), and priorityDomain when the caller’s verified domain gives it priority over someone else’s unfinished registration. The row then shows the name as if that registration were not there: available, say, with the reason “You have priority as the verified owner of starwars.com.” state is one of:

suggestions holds up to three { name, tld, state } alternatives, in the namespace that was typed (or .character), when that one is not available. Each has been checked and is available or requires rights.

GET/v1/lookup/:address

Auth

None.

Answer

A public view of any born name, with the status read live: { name, address, pid, tld, family, state, ownerLabel, relationshipLabel, displayName, bornAt, certificate, certificateHistory[], corrected, view, formerNames[] }. The address may use any scheme and may be percent-encoded; address is the corrected one, and certificate is the current signed certificate.

Errors

400 for an invalid address; 404 not_found, “oasis.character is not a registered portal name.”

formerNames lists the names that held a released address before the current one, each { pid, releasedAt, certificateUrl }, so anyone can see that the address now belongs to a different character and read the former one’s death certificate. When the address has not been registered again, the answer is the most recent former name itself, in its released state. See No resurrection.

GET/v1/certificates/:pid

Auth

None.

Answer

{ certificate, fingerprint, pdfUrl, history[] }, cacheable for a minute. certificate is the current one (the death certificate once retired). Each history entry is { certificateId, kind, version, issuedAt, supersededAt, fingerprint, certificate }. See Certificates.

Errors

404 not_found, “There is no certificate for that permanent ID.”

GET/v1/resolve/:address

Auth

None.

Answer

A 307 redirect to the same address on the first PNS server, query included, so ?time= and ?dir= carry through. See Resolution.

GET/v1/auth/login?return=/dashboard

Auth

None.

Answer

A redirect to Jubilee ID (OpenID Connect with PKCE). After sign-in the browser comes back to the registry website at return (a path on the site; anything else becomes /dashboard), or to /welcome/?return= for a new account that has not yet chosen its type. The session cookie is set on the way.

GET/v1/auth/callback

Auth

Called by Jubilee ID only, never by a client.

Answer

Finishes the sign-in, sets the session cookie, and redirects to the site as above. A sign-in error from Jubilee ID redirects to /signin/?error=.

Errors

400 invalid_request, “The sign-in response was incomplete. Please sign in again.”; 403 forbidden, “This account is suspended. Contact support.”

POST/v1/auth/logout

Auth

None needed; the Origin check applies.

Answer

{ "ok": true }. The session, if there is one, is revoked and the cookie cleared.

POST/v1/auth/dev-login

Auth

Development and test registries only; everywhere else it answers 404.

Body

{ "email": "...", "displayName"?: "...", "type"?: "individual" | "organization", "jubilee"?: true }

Answer

{ token, account }: a session without Jubilee ID, for local development and the test suite. /v1/config reports it as devLogin.

GET/v1/me

Auth

Signed in (session).

Answer

{ account, mfa: { enrolled, satisfied } }, where account is { id, type, displayName, email, verification, twoFactor, needsAccountType }.

Errors

401 unauthorized, “Please sign in with your Jubilee ID.”

POST/v1/me/account-type

Auth

Signed in (session).

Body

{ "type": "individual" | "organization", "displayName"?: "...", "contact"?: { "name", "email", "phone"? } }. The display name (up to 120 characters) is the public owner label on certificates. An organization must give an accountable point of contact, which is kept private.

Answer

{ account }

Errors

400 invalid_request, “Organizations give an accountable point of contact: a name and an email. It is kept private.”; 409 status_conflict, “The account type cannot change once the account holds names.”

POST/v1/me/mfa/enroll

Auth

Signed in (session).

Answer

{ secret, otpauthUri }. Show the URI as a QR code for an authenticator app, then confirm with a code.

Errors

409 status_conflict if two-factor is already set up.

POST/v1/me/mfa/confirm

Auth

Signed in (session).

Body

{ "code": "123456" }

Answer

{ "ok": true, "twoFactor": true }. Confirms enrollment, and this session now has two-factor.

Errors

401 unauthorized, “That code did not match. Check your authenticator app's time and try again.”

POST/v1/me/mfa/verify

Auth

Signed in (session).

Body

{ "code": "123456" }

Answer

{ "ok": true, "twoFactor": true }: a later session steps up to two-factor.

Errors

400 invalid_request, “Finish setting up two-factor authentication first.”; 401 unauthorized as above.

GET/v1/me/verifications

Auth

Signed in (session).

Answer

{ verifications: [{ id, kind, level, state, result, decided_at, created_at, pid }] }. Note the field names in this answer are written with underscores.

POST/v1/me/verifications

Auth

Signed in, with two-factor authentication on the session.

Body

{ "kind": "identity" | "organization", "evidence": [{ "name"?, "contentType", "data" }] }. Identity verification is for a person’s own (individual) account; organization verification for an organization account. One to four files, each a JPEG, PNG or WebP image or a PDF under 4 MB, with data in base64 or base64url.

Answer

201 { id, state: "submitted" }. The account’s names waiting for this kind of verification now point at it.

Errors

409 status_conflict, “A verification of this kind is already waiting for review.”

Jubilee reviews the evidence and deletes it the moment it decides; only the result is kept. An approval is reused for every name the account registers that needs it.

GET/v1/team

Auth

Signed in (session).

Answer

{ members: [{ accountId, role, displayName, email }], invites: [{ id, email, role, createdAt, expiresAt }], memberships: [{ orgAccountId, role, displayName }] }: the account’s own team and pending invitations, and the organizations it belongs to.

POST/v1/team/invites

Auth

Signed in as the organization, with two-factor.

Body

{ "email": "staff@example.com", "role": "admin" | "editor" | "viewer" }

Answer

201 { id, acceptUrl, token, emailed: true }. The invitation is emailed to that address; acceptUrl is the same link, for sharing another way. It is valid for 14 days and must be accepted by the invited email address.

POST/v1/team/accept

Auth

Signed in, with two-factor authentication on the session.

Body

{ "invite": "inv_...", "token": "..." }

Answer

{ "ok": true, "orgAccountId": "acc_...", "role": "editor" }

Errors

404 not_found, “That invitation is not valid or has expired.”; 403 forbidden for another email address.

PUT/v1/team/members/:accountId

Auth

Signed in as the organization, with two-factor.

Body

{ "role": "admin" | "editor" | "viewer" }

Answer

{ "ok": true }

DELETE/v1/team/members/:accountId

Auth

Signed in as the organization, with two-factor.

Answer

{ "ok": true }

POST/v1/names

Auth

Signed in, with two-factor authentication on the session.

Body

A Worker character, registered by an organization:

{
  "name": "oasis.character",
  "relationshipLabel": "AI Employee",
  "responsibleGuardian": "Jordan Lee",
  "gender": "female",
  "affirmResponsibility": true,
  "displayName": "Oasis",
  "acceptRules": true,
  "acceptTerms": true,
  "turnstileToken": "<token from the human check>"
}

For any .character: gender (male, female or other) and affirmResponsibility: true, the affirmation in the registry’s words. A person adds registrantRole, father or mother, and a Family relationshipLabel (the certificate’s label is set from the Character DNA at birth); an organization adds its title as relationshipLabel (AI Employee when none is given) and responsibleGuardian, a person’s name. Any name may add a displayName (up to 120 characters), which need not be unique. See Characters.

Answer

201 { name, next, priority? }, where name is the name’s view (below). priority is { domain } when the caller’s verified domain released someone else’s unfinished registration of the same name (see Domain proof).

Errors

• 400 invalid_request: the account type is not chosen; the rules or terms are not accepted; the relationship label is missing or wrong; a character without its gender (“Choose the character's gender: male, female or other. It stays on the birth certificate.”), its affirmation, a Parent shown as father or mother (“Choose whether you are shown as the father or the mother. A Family character has exactly one Parent.”), or an organization’s Responsible Guardian; a Worker title with a family word (“A Worker character's label is "AI" and your title for it, such as AI Employee or AI Representative.”).
• 403 verification_required, “Verify your email address with Jubilee ID first.”; 403 turnstile_failed; 403 not_offered; 403 reserved_name; 403 forbidden for the wrong kind of account.
• 409 account_review, “This account is being reviewed because it holds many names. We will email you when the review is finished.” The first time an account passes the threshold, the review opens and the message says how many names it holds.
• 409 name_taken, “oasis.character is already registered by Example Studio.”
• 429 cap_reached, “You have reached the limit of 10 new .character names in 30 days.”; 429 rate_limited.

A new name is held for 60 minutes while its registrant pays; an unpaid hold expires and gives the label back. A name that needs review (a look-alike, a reserved name someone asks for, a tragedy, or any .figure, subnames included) is held until the review decides; holding a reservation never skips a review the namespace requires. A subname is made by an admin of its parent, which must be born; it is paid at once, at no charge. A subname whose leaf is a reserved label is refused with 403 reserved_name, “"persona" is a reserved label: oasis.character already answers persona.oasis.character itself.” A person’s first avatar is their primary avatar.

GET/v1/names

Auth

Signed in (session).

Answer

{ names: [...] }: the account’s own names, and those of every organization it is a member of, each with the account’s role. Each name’s autoRenew says whether the card on file renews it.

GET/v1/names/:pid

Auth

Signed in; the viewer role or higher.

Answer

{ name, next, records, certificate, certificateUrl, statusReason, reviews[], transfers[], recovery, versionFloors, keyId, nextKeyId }. next is as above. records are the stored signed envelopes. recovery is the open key recovery of the name, { id, kind, state, createdAt, expiresAt, readyAt }, or null (see Recovery). keyId is the key id every new owner record must carry (the current key), or null before birth; nextKeyId is an older name for the same value. versionFloors is explained under PUT records.

POST/v1/names/:pid/checkout

Auth

Signed in, with two-factor authentication; the admin role or higher on the name.

Body

{ "autoRenew"?: true | false }. Automatic renewal is on unless this is false: Stripe saves the card for the registry to charge before each term ends (see Automatic renewal). Subnames, and registrations that do not expire, never save a card.

Answer

{ url, sessionId, autoRenew }: send the person to url, a Stripe Checkout page. autoRenew says whether the card will be saved. The hold is extended to 24 hours. Stripe returns to https://theportalmesh.com/register/<name>/?paid=1&pid=<pid>, and the name becomes paid when Stripe confirms the payment to the registry.

Account credit is spent first. When it covers the whole price, nothing goes to Stripe: the answer is { url, sessionId: null, autoRenew: false, paidWithCredit: true, outcome }, the name is already paid, and the client goes to url all the same.

A free name, an .avatar, answers { url, sessionId: null, autoRenew: false, paidWithCredit: false, free: true, outcome: "paid" } with no Stripe at all. A realm answers { url, sessionId, autoRenew, held: true }: Stripe holds the $1,000 on the card, and the card is kept, until Jubilee decides its charter (below). Credit is never spent on a realm.

Errors

• 403 identity_required before an account’s first paid registration, with detail.verify set to identity or organization: “Verify your identity with Jubilee before your first paid registration. Every account on the Mesh is a verified person or organization, so names cannot be hoarded.”
• 409 charter_required for a realm without its charter: “File the realm charter for heaven.realm first: its purpose, rules, content rating and Responsible Guardian.”
• 403 verification_required, “This name is waiting for review. You can pay once it is approved.”; 409 status_conflict, “The hold on this name expired before payment. Please search again.”; 429 cap_reached.

POST/v1/names/:pid/charter

Auth

Signed in, with two-factor authentication; the owner role or higher on the name.

Body

{
  "purpose": "A depiction of Heaven drawn from Revelation 21 and 22, for worship and teaching.",
  "rules": "Visitors come as their own verified avatars. No violence, no commerce, an exit that always works.",
  "contentRating": "all",
  "responsibleGuardian": "Jordan Lee"
}

Answer

201 { charter }, where charter is { purpose, rules, contentRating, responsibleGuardian, state, decidedAt, note, createdAt } and state is submitted, approved or rejected. A realm only, and only before its fee is held; filing again replaces it.

Errors

400 invalid_request: “The charter needs its purpose (at least 20 characters).”, the same for its rules; a content rating that is not one of all, teen, mature, adult (any letter case) is refused with “Choose the realm's content rating: all (All ages), teen (Teen (13 and older)), mature (Mature (17 and older)), adult (Adult (18 and older)).”; and a Responsible Guardian of fewer than 3 characters. 409 status_conflict once the charter is with Jubilee for a decision.

The charter is decided by hand in the Customer Admin. Approval takes the held payment (or charges the saved card, if the hold has lapsed) and the realm is paid; rejection releases the hold. The applicant is emailed either way, and the Portal Server enforces the approved charter at the door. GET /v1/names/:pid/charter (any role on the name, with two-factor) answers { charter }, or { charter: null }.

POST/v1/names/:pid/verify

Auth

Signed in, with two-factor authentication; the admin role or higher on the name.

Body

For identity and organization namespaces, { "evidence": [...] } as for account verification. For a figure, { "evidence"?: [...], "figure": { "reason": "...", "diedYear"?: 1799, "rightsHolderPermission"?: true, "notWorshipped": true } }, with a documented reason of at least 20 characters.

Answer

201 { state: "submitted", verificationId }, or 200 with the existing state when a verification is already approved or waiting. Other namespaces answer “This namespace needs no separate verification step.”

Errors

400 invalid_request, “Confirm that this person is not worshipped or venerated as divine, nor the founding prophet of a religion.”

POST/v1/names/:pid/birth

Auth

Signed in, with two-factor authentication; the admin role or higher on the name.

Body

{ publicKey, personaPackage? }: the name’s Ed25519 public key as a JWK, generated on the registrant’s device, and for a persona namespace the persona package. The private key is never sent.

{
  "publicKey": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
  },
  "personaPackage": "<the persona package, for .character, .avatar and .figure>"
}

Answer

201 { pid, certificate, certificateFingerprint, certificateUrl, pdfUrl, jsonUrl, records, keyId, personaProfileUrl }. records are the new ID, STATUS (born) and CERT records; keyId is <pid>#k1; personaProfileUrl is where the persona package was published, or null.

Errors

402 payment_required, “Complete payment before birth.”; 403 verification_required; 400 invalid_request, “Send the Ed25519 public key as a JWK. The private key stays with you.” or “A persona package is needed: its fingerprint is written into the birth certificate.”; 409 status_conflict if already born, and always for a .character, with detail.reason: "born_by_engine": a character is born by the birth engine the moment its registration is paid for (The birth engine).

PUT/v1/names/:pid/records

Auth

Signed in, with two-factor authentication; the editor role or higher on the name.

Body

{ "records": [...], "remove"?: [{ "type", "kind"? }], "personaPackage"? }: up to 20 signed owner records, slots to remove, and the new persona package when a PERSONA record changes the persona. Only while the name is born or active. See Records and signing for every rule.

Answer

{ ok, serial, records, recertified, missing, versionFloors }: the new serial, every stored record, whether the birth certificate was re-issued, what is still missing, and the version floors.

Errors

422 invalid_record, with the first problem as the message and all of them in detail.problems; 422 required_records_missing when a change would leave an active name without a record it needs (“An active name must keep ENDPOINT.”); 409 status_conflict.

Every new record must be numbered above both the slot’s stored version and its floor. When an owner removes a record, the registry keeps the highest version that slot held as its floor, so an older signed copy can never be put back. versionFloors lists the floors, keyed "TYPE" or "TXT:kind", for example { "ENDPOINT": 3, "TXT:rating": 1 }: a new ENDPOINT must then be version 4 or higher. Records dropped by a key rotation or a transfer leave no floor, because they can never verify again.

A character’s experience CONSENT is uploaded here like any owner record, in the slot CONSENT:<experience>; to remove one, send { "type": "CONSENT", "kind": "<experience>" } in remove. Removing it, or replacing it for another script, withdraws the consent: the registry tells the Character Server at once, and the character leaves that experience.

GET/v1/names/:pid/activation-check

Auth

Signed in; the viewer role or higher.

Answer

{ ready, missing[], problems[] }: exactly what activation would check, without activating.

POST/v1/names/:pid/activate

Auth

Signed in, with two-factor authentication; the admin role or higher on the name.

Body

{ "modes": ["text", "voice"], "directions": ["bring"] }. Each must be offered by the ENDPOINT record; empty lists take the ENDPOINT’s.

Answer

{ name, manifest, snippet }: STATUS becomes active and is published, and the answer carries the portal.json manifest and the portal.js snippet. Calling it again on an active name changes its modes and directions.

Errors

422 required_records_missing, “Still needed before activation: PERSONA, ENDPOINT.” with detail.missing; 422 signature_invalid for any other problem (a signature, a pending review, an ALIAS target that is not live), with detail.problems; 400 invalid_request, “The ENDPOINT does not offer hologram.”; 409 status_conflict.

POST/v1/names/:pid/rotate-key

Auth

Signed in, with two-factor authentication; the admin role or higher on the name. The request must also be signed by the name’s current key: the proof.

Body

{ "publicKey": { JWK }, "proof": "...", "records"?: [...], "reason"?: "..." }. proof is required: the current key’s signature over a pm.key-rotation/1 statement (below), so the current key file must be opened. Records are signed with the new key, whose id is <pid>#k<n+1>.

Answer

{ keyId, keyVersion, certificateId, name, droppedRecords }: a new ID record and a re-issued birth certificate. The owner is emailed, and any open key recovery of the name is canceled: whoever holds the current key outranks a recovery request.

Errors

• 403 key_proof_required without a proof, with the statement to sign in detail.statement: “Sign the rotation with oasis.character's current key file. If the key is lost, start a recovery from your dashboard instead.”
• 422 signature_invalid, “The rotation is not signed by oasis.character's current key (<pid>#k1).”, also with detail.statement.
• 422 required_records_missing: an active name must send every owner record re-signed with the new key in the same request, and the answer lists the ones missing. 422 signature_invalid for a record that does not verify against the new key; 422 invalid_record for one that is malformed or not newer than the slot’s current version.
• 409 status_conflict unless the name is born or active.

A born name that is not yet active may rotate without records; its old owner records are dropped and listed in droppedRecords.

{
  "publicKey": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "_FHNjmIYoaONpH7QAjDwWAgW7RO6MwOsXeuRFUiQgCU"
  },
  "proof": "4u7awgL7_fIZPFMHx5PMokcbs3KYZaOSpQev3Svbxb-0Ayfk3X38zZWK0PRwHo0lo1ooNvhF4thB6rvyK06gAg",
  "records": [
    "<every owner record of an active name, re-signed with the new key and numbered above its current version>"
  ],
  "reason": "Scheduled key rotation"
}

POST/v1/names/:pid/transfer

Auth

Signed in, with two-factor authentication; the owner role or higher on the name.

Body

{ "toEmail": "new.owner@example.com", "affirmNoSale": true }

Answer

201 { id, acceptUrl, token, emailed: true }. The recipient is emailed the offer, and the owner is emailed a notice in case the account is not in the owner’s hands; acceptUrl is the recipient’s link, for sharing another way. The transfer is open for 14 days; one at a time per name.

Errors

400 invalid_request without affirmNoSale: true, “Names are never resold on the Mesh. Affirm that no money is changing hands for this name to continue.”; 403 transfer_refused, “An avatar is bound to one person for life and can never be transferred.”; 409 status_conflict, “A transfer of this name is already waiting. Cancel it first.”

Names cannot be resold: every transfer goes through Jubilee, at cost. The holder starts it, the recipient accepts it, and Jubilee approves it; when there is a fee, the recipient pays it from an emailed link, and the name moves once it is paid.

GET/v1/transfers/incoming

Auth

Signed in, with two-factor authentication on the session.

Answer

{ transfers: [{ id, createdAt, expiresAt, name, pid, keyVersion, tld }] }: open transfers sent to the account’s email.

POST/v1/transfers/:id/accept

Auth

Signed in, with two-factor, as the account the transfer was sent to.

Body

{ "token": "...", "publicKey": { JWK }, "affirmNoSale": true, "relationshipLabel"?: "...", "registrantRole"?: "..." }

Answer

{ transfer: { id, state: "approval", feeCents } }. Both people are emailed that the transfer waits for Jubilee’s approval. feeCents is what the recipient will pay, if anything.

Errors

400 invalid_request without affirmNoSale: true, “Names are never resold on the Mesh. Affirm that you paid nothing for this name to continue.”; 403 transfer_refused for a Family character and an organization, “A Family character can never be transferred to an organization. An organization creates its own Worker character instead.”; 404 not_found, “That transfer is not valid or has expired.”

Once Jubilee approves it, and any fee is paid, the new owner’s key takes over. The previous owner’s key, and every record it signed, stop counting: the birth certificate is re-issued for the new registrant, owner records are dropped, and an active name returns to born until its new owner activates it. The name arrives with automatic renewal off, because the previous owner’s card no longer pays for it. The previous owner is emailed when the transfer completes.

POST/v1/transfers/:id/cancel

Auth

Signed in, with two-factor, as the sender.

Answer

{ "ok": true }. An open transfer, one waiting for approval, or one waiting for its fee.

POST/v1/names/:pid/retire

Auth

Signed in, with two-factor authentication; the owner role or higher on the name.

Body

{ "confirmName": "oasis.character", "reason"?: "..." }

Answer

{ name, deathCertificateId, confirmed, servers[] }: 200 once all four PNS servers have confirmed the retirement, 202 when it is not yet confirmed (it keeps being published). A death certificate is issued and the permanent ID is never reused.

Errors

400 invalid_request, “Type oasis.character to confirm. Retirement is permanent and the permanent ID is never reissued.”

POST/v1/names/:pid/renew

Auth

Signed in, with two-factor authentication; the admin role or higher on the name.

Body

{ "autoRenew"?: true | false }. As at checkout, paying by hand also saves the card and turns automatic renewal on, unless this is false.

Answer

{ url, sessionId, autoRenew }: a Stripe Checkout for the next term, which returns to https://theportalmesh.com/dashboard/?renewed=<name>. When account credit covers the price, { url, sessionId: null, autoRenew: false, paidWithCredit: true, outcome }: the name is already renewed. A free name renews the same way with free: true. Either way a receipt is emailed. A sleeping character renews like an active one, and a dormant name is revived by the renewal at once, to the state it was in.

Errors

400 invalid_request, “Subnames renew with their parent.”; 409 status_conflict, “A suspended name cannot be renewed until the suspension is lifted.”, and for a name that has died or ended: “oasis.character cannot be renewed while dead.” There is no resurrection; see The life of a name.

POST/v1/names/:pid/grant

Auth

Signed in, with two-factor; any role on the name. The Origin check applies.

Body

{ "server": "character" | "portal" | "experience" }

Answer

{ token, expiresAt }: a pmg1 token, good for five minutes at that server only, naming the account, the name, its PID and the caller’s role on it. The server checks it with the published grant key. The role limits what the server allows: owners and admins change settings, editors edit content, viewers read.

Errors

400 invalid_request, “Name the server: character, portal or experience.”, or for the wrong server: “oasis.character is served by the Character Server.”

GET/v1/grant-key

Auth

None.

Answer

{ keys: [{ kid, x }] }, cacheable for an hour: the public half of the registry’s grant key, an Ed25519 key that is not the root key. A grant vouches for an account, never for a record.

Errors

503 config_error, “The owner grant key is not configured.”

POST/v1/names/:pid/succession

Auth

Signed in, with two-factor authentication; the owner role or higher on the name.

Body

{ "successorName": "Ann Brown", "successorEmail": "ann@example.com", "backupName"?: "...", "backupEmail"?: "..." }

Answer

{ ok: true, successorDesignated: true }. A .character’s guardianship designation, like a will: filing again replaces it. The emails are kept private, and the GUARDIAN record is re-issued saying successorDesignated: true.

Errors

400 invalid_request, “Name a successor: the person who becomes the character's Guardian if you no longer can.” or “Give the successor's email, so Jubilee can reach them. It is never published.”

POST/v1/succession/accept

Auth

Signed in, with two-factor, as the email the invitation was sent to.

Body

{ "pid": "pid:...", "token": "...", "affirmResponsibility": true }

Answer

{ ok: true, name, status }. After a death report confirmed by Jubilee, the successor (or else the backup) is emailed a link, /succession/?pid=<pid>&token=<token>. Accepting it, with the guardianship affirmation, moves the character to their account: it runs again, GUARDIAN says succeeded, and the Parent stays on the birth certificate.

Errors

400 invalid_request, “Affirm: "I accept the duties and responsibilities of guardianship for this AI character."”; 403 forbidden, “Sign in with the email this invitation was sent to.”; 404 not_found, “That link is not valid any more.”; 409 status_conflict when the character is not waiting for a Guardian.

With nobody stepping in within 180 days, the character is retired with a death certificate. See Succession.

GET/v1/me/billing

Auth

Signed in (session).

Answer

{ card, renewalMode, daysBefore, creditCents, names[] }. card is { brand, last4, expMonth, expYear, label } or null; daysBefore is how many days before expiry the card is charged; creditCents is the account credit. Each of names is { pid, name, expiresAt, autoRenew, eligible } for the account’s own top-level names, where eligible is false for a name that cannot renew in its present state.

POST/v1/me/billing/card

Auth

Signed in, with two-factor authentication on the session.

Answer

{ url, sessionId }: a Stripe Checkout in setup mode, which saves a card without charging it and returns to https://theportalmesh.com/dashboard/?card=saved. The new card replaces any earlier one.

DELETE/v1/me/billing/card

Auth

Signed in, with two-factor authentication on the session.

Answer

{ ok: true, namesTurnedOff }: the card is never charged again, and automatic renewal is off for every name.

Errors

404 not_found, “There is no card on file.”

POST/v1/me/billing/auto-renew

Auth

Signed in, with two-factor authentication on the session.

Body

{ "enabled": true | false }

Answer

{ ok: true, changed }: automatic renewal is switched for every eligible name the account holds itself.

Errors

400 invalid_request, “Say whether automatic renewal is on or off.”; 402 payment_required, “Save a card first; automatic renewal charges it shortly before each name expires.”

PUT/v1/names/:pid/auto-renew

Auth

Signed in, with two-factor authentication; the admin role or higher on the name.

Body

{ "enabled": true | false }

Answer

{ autoRenew, card }: the new setting and, when switching it on, the card that will be charged (the name owner’s); card is null when switching it off.

Errors

402 payment_required, “Save a card first; automatic renewal charges it shortly before the name expires.”; 409 status_conflict for a subname, “Subnames renew with their parent name.”, or a name that cannot renew in its present state.

GET/v1/me/domains

Auth

Signed in (session).

Answer

{ domains: [...] }, each { id, domain, label, state, createdAt, verifiedAt, checkedAt, lastError, record: { name, type: "TXT", value } }, where state is pending, verified or lapsed, record is what to publish, and lastError says what the last check found, such as “The TXT record was not found yet. DNS changes can take a while to appear.”

POST/v1/me/domains

Auth

Signed in, with two-factor authentication on the session.

Body

{ "domain": "https://www.StarWars.com/about" }: anything a person types; it is read as shown above.

Answer

201 { domain }, the new claim with its record, or 200 with the existing claim when the account already has it.

Errors

400 invalid_request with the reason, such as “Claim the registered domain itself, starwars.com, not a subdomain of it.”; 429 cap_reached, “An account can hold 20 domain claims. Withdraw one you no longer need.”

POST/v1/me/domains/:id/check

Auth

Signed in (session).

Answer

{ found, domain }: found is true when the record is there (the claim is now verified), false when it is not, and null when the DNS lookup itself failed, so try again later. domain is the claim as it now stands.

Errors

404 not_found, “There is no domain claim with that id on your account.”

DELETE/v1/me/domains/:id

Auth

Signed in, with two-factor authentication on the session.

Answer

{ "ok": true }: the claim is withdrawn.

GET/v1/names/:pid/recovery

Auth

Signed in; the owner of the name.

Answer

{ level, path: "confirm" | "review", waitHours, confirmHours, open }: what a lost-key recovery of this name will ask for, how long the confirmation link lasts and the wait after it, and the open recovery, if there is one.

POST/v1/names/:pid/recovery

Auth

Signed in, with two-factor authentication; the owner role or higher on the name.

Body

{ "publicKey": { JWK }, "statement"?: "...", "evidence"?: [...] }. The new key is made like any other, with the next key id, <pid>#k<n+1>, and saved in a new key file. The review path needs statement and, for identity and organization levels, evidence (as for verifications).

Answer

201 { recovery }. On the confirm path the account is emailed the confirmation link.

Errors

• 400 invalid_request, “Make a new key for the name and send its public key as a JWK.”; “That is the key the name already has. Make a new one.”; “Explain what happened in at least 20 characters, for the reviewer.”; “Attach fresh identity evidence: the same kind this name needed at registration.”
• 409 status_conflict, “A recovery of oasis.character is already under way. Cancel it first to start again.”, or for a name that is not born or active: “oasis.character is suspended; recovery waits until it is restored.”

POST/v1/recoveries

Auth

Signed in, with two-factor authentication on the session.

Body

{ "name": "oasis.character", "publicKey": { JWK }, "statement": "...", "evidence": [...] }

Answer

201 { recovery }. The account holding the name is emailed.

Errors

• 404 not_found, “That is not a registered portal name.”
• 400 invalid_request, “oasis.character is already on this account. Recover its key from your dashboard instead.” or “Attach evidence that the name is yours: receipts, the key file's public key, correspondence, or identity documents.”
• 403 forbidden when the requesting account could not hold the name (an organization’s name is recovered from an organization account).
• 409 status_conflict, “Your request to recover oasis.character is already with a reviewer.”

GET/v1/recoveries

Auth

Signed in (session).

Answer

{ recoveries: [...] }: the recoveries the account asked for, and those of names it holds, newest first. Each is { id, pid, name, kind, state, path, createdAt, expiresAt, readyAt, completedAt, outcome, role }, where kind is key or account and role is requester or holder.

POST/v1/recoveries/:id/confirm

Auth

None: the token from the email is the proof. The Origin check applies.

Body

{ "token": "..." }

Answer

{ recovery }, now waiting. The email’s link opens https://theportalmesh.com/recovery/?id=<id>&confirm=<token>.

Errors

404 not_found, “That confirmation link is not valid or has expired. Start the recovery again from your dashboard.”

POST/v1/recoveries/:id/cancel

Auth

The token from any recovery email (/recovery/?id=<id>&cancel=<token>), or signed in as the requester.

Body

{ "token"?: "..." }

Answer

{ recovery }, now cancelled. Any evidence sent with it is deleted.

Errors

403 forbidden, “Only the person who started this recovery, or the link in its email, can cancel it.”; 404 not_found, “There is no open recovery with that id.”

GET/v1/support/tickets

Auth

Signed in (session).

Answer

{ tickets: [{ id, subject, category, state, pid, createdAt, updatedAt }] }, most recently updated first, where state is open, waiting or closed.

POST/v1/support/tickets

Auth

Signed in (session).

Body

{ "subject": "...", "body": "...", "category"?: "general" | "billing" | "registration" | "verification" | "technical", "pid"?: "pid:..." }. The subject is at least 3 characters and the message at least 10. A pid counts only for a name the account holds.

Answer

201 { id }

Errors

400 invalid_request, “Write the subject (at least 3 characters).”; 429 rate_limited, “You have many open requests. Please add to one of them instead.”

GET/v1/support/tickets/:id

Auth

Signed in (session).

Answer

{ ticket, messages: [{ id, author: "customer" | "staff", from: "You" | "Jubilee support", body, createdAt }] }. Staff replies are signed “Jubilee support” and are also emailed; staff’s internal notes are never shown.

Errors

404 not_found, “No such request.”

POST/v1/support/tickets/:id/messages

Auth

Signed in (session).

Body

{ "body": "..." }

Answer

201 { "ok": true }. A reply opens the request again if it was closed.

POST/v1/support/tickets/:id/close

Auth

Signed in (session).

Answer

{ "ok": true }

POST/v1/abuse

Auth

Anyone, signed in or not. The human check and the Origin check apply.

Body

{ "name": "oasis.character", "category": "impersonation" | "harmful" | "rights" | "spam" | "other", "details": "...", "email"?: "...", "turnstileToken": "..." }. The details are at least 20 characters; the name may be written as an address.

Answer

201 { id, registered }: registered says whether the reported name is registered. With an email (or signed in), the reporter is emailed that the report arrived.

Errors

400 invalid_request, “Choose what is wrong: impersonation, harmful, rights, spam, other.”; 403 turnstile_failed

Support staff read every report. One that breaks the namespace rules is passed to the people who run Portal Name Services, who can suspend a name on every server. See How the Mesh is run. The Report button on every character, place and experience lands here too; from a Mesh server it may also say a report involves a minor, which asks for the name’s suspension at once while it is reviewed.

GET/v1/servers

Auth

None.

Answer

{ servers: [{ kind, title, namespaces, summary, download }], hosting: "jubilee" }, cacheable for five minutes: the three Mesh servers, which Jubilee hosts for every customer. download is the server’s self-host package, { version, file, sha256, bytes, builtAt, url }, or null until one is published. The url is on the files host (/downloads/); check the file against sha256 before running it.

GET/v1/me/servers

Auth

Signed in (session).

Answer

{ servers: [{ id, kind, title, label, state, pendingAction, createdAt, updatedAt, names, usage, health }] }: the servers hosting is on for, for this account’s names. state is running (on), paused or requested (asked for before hosting opened). names is { total, live, namespaces: [{ tld, count, names }], truncated }: the account’s paid, born, active, sleeping, suspended and dormant names in that server’s namespaces. usage is the Character Server’s latest storage report, { storageBytes, characters, measuredAt, includedBytesPerCharacter, overageBytes }, or null for the other servers. health is { state: up | down | unreachable | unknown, checkedAt, message }, fetched from the server when you ask, with a 2.5-second limit. pendingAction is a restart, pause or resume support has recorded, or null; it is not carried out on the server yet.

POST/v1/me/servers

Auth

Signed in, with two-factor authentication on the session.

Body

{ "kind": "character" | "portal" | "experience", "label"?: "..." }. The label (2 to 80 characters) defaults to the server’s title.

Answer

201 { id, state: "running", server }: hosting is on at once, since Jubilee’s servers host every customer and nothing is set up for one account. Asking again answers 200 with the same entry.

Errors

400 invalid_request, “Choose the Character, Portal or Experience Server.”

DELETE/v1/me/servers/:id

Auth

Signed in, with two-factor authentication on the session.

Answer

{ "ok": true }: hosting is turned off. Jubilee’s server still answers for a live name whose ENDPOINT points at it; this records that you mean to run those names elsewhere.

Errors

404 not_found, “No such server.”

GET/v1/me/access-log

Auth

Signed in (session).

Answer

{ entries: [{ who, reason, at }] }, newest first: each time Jubilee support looked at the account as the customer sees it, and the reason they gave. That view is read only.

GEThttps://files.theportalmesh.com/<path>

Auth

None.

Answer

Public files only: portal.js, portal.min.js and the source map, and anything under certificates/, personas/, packages/, worlds/ and media/. Everything else is a 404, whether or not it exists; verification evidence can never be fetched by address. Open to any origin; certificates and persona packages are cached as immutable, portal.js for five minutes.

POST/v1/stripe/webhook

Auth

Stripe only: every event is checked against its signature before anything in it is read.