Admin Tokens - Self-service issuance

1. What is an admin token?

An admin token is a 43-character opaque credential that authenticates a single email address as an operator of Datachain Rope's administrative surface: reviewing incoming project submissions, moderating node-deploy requests, tracking integration tickets, and running critical-protocol governance actions.

Tokens are prefixed by role so a leaked one is recognisable at a glance:

Prefix	Role	Grants
dcrope_pa_<43>	Project admin	Review submissions, approve critical-protocol proposals, gate ecosystem & integration audit
dcrope_na_<43>	Node admin	Approve node-deploy requests, list pending queue, sign off on databox / Rope-CLI deploys
dcrope_ma_<43>	Multi-role	Both of the above in a single token. Emitted when the requester's email is eligible for both roles at request time.

2. Roles & eligibility

2.1 project_admin - allowed domains

Any email whose domain matches one of the built-in project-admin allowlist domains is eligible for a project_admin token at any time.

• onguene.com
• onguene.org
• datachain.one
• datachain.network
• databox.network
• databØx.com (Unicode; also matches its Punycode form xn--databx-yta.com)

2.2 node_admin - allowed domains + declared operators

Same built-in allowlist as above, plus any email that has been declared as a node deployer / owner through one of the following surfaces:

• https://datachain.network/ - "Deploy a Datachain Rope Node" form
• https://datachain.network/ - "Submit Your Project" form (project owner email counts as an operator email)
• The Rope CLI (ropectl deploy-node --owner-email <email>)
• Ecosystem Deployment Console - Databox / Community / Federation deploys
• Direct entry in node-requests.jsonl / projects.jsonl (any status - pending, approved, fulfilled)

2.3 multi_role - both

If the requesting email is eligible for both project_admin (through domain) AND node_admin (through domain OR declaration), a single multi_role token is issued. It satisfies both role checks on every gated endpoint.

3. Lifecycle & renewal

Time-to-live	7 days (ADMIN_TOKENS_TTL_SECS, default 604800)
Auto-renewal	Every 3600 s a background task looks for active records whose expires_at is within 24 h. It mints a fresh token for the same email, emails it to the same address, and revokes the previous one in the same transaction.
One-active-per-email	Requesting a new token for an already-active email rotates: the previous token is revoked and a fresh one is issued. This keeps the audit surface small.
Storage	Append-only JSON-lines at /opt/datachain-rope/admin-tokens.jsonl. Runtime map is rebuilt from this file at startup so a corrupt or partial write cannot brick admin access.
Chain anchoring	Every issue & revoke event is anchored as an AdminTokenIssued / AdminTokenRevoked Quipu knot on the dedicated ledger wallet 0x000000000000000000000000000000000000d005 via rope_appendToLedger.

4. Request a token

Fill in your email. If your address is eligible (see §2), a token is issued and emailed to you within a few seconds. The best role you qualify for at that moment is picked automatically.

Website

Your email * The token will be sent to this address. If it is eligible for both project_admin and node_admin, a single multi_role token is issued.

Request token

5. Use your token

Present the raw token in the X-Admin-Token header on any protected endpoint.

Common gates that consume the token:

Endpoint	Role required
GET /api/v1/node-requests	node_admin or multi_role
POST /api/v1/node-requests/:id/review	node_admin or multi_role
GET /api/v1/integration-requests	project_admin or multi_role
POST /api/v1/projects/:id/review	project_admin or multi_role
POST /api/v1/projects with critical_protocol=true	project_admin or multi_role
GET /api/v1/admin-tokens (audit)	project_admin or multi_role

6. Revoke a token

A holder can revoke their own token by supplying it in both the X-Admin-Token header and the request body. A different project_admin (or multi_role) holder can revoke someone else's token by supplying their own token in the header and the target token in the body.

Your admin token * Sent as X-Admin-Token. Must carry the project_admin role (a multi_role token also works).

Token to revoke * Can be the same as your auth token (self-revocation) or a different one you have the authority to revoke.

Reason (optional)

Revoke

7. Audit active tokens

Read-only inventory of currently-active token records. Only hash prefixes (first 12 characters of the SHA-256) are shown - full tokens are never returned by this endpoint.

Your admin token * Must carry the project_admin role (a multi_role token also works).

List active tokens

8. Founder bootstrap

The very first token issued on a fresh store must be signed by an Ed25519 founder key listed in deploy/config/master-nodes.toml. This is a one-off, offline procedure - once one admin exists, they can rotate the store as a normal operator.

8.1 Canonical signing message

Where role_csv is exactly one of project_admin, node_admin, or project_admin,node_admin (the multi-role form). The signer must match one of the configured founder public keys; the timestamp must be within the freshness window (default ±10 minutes).

8.2 POST body

9. Security model

• Blast radius per token: one email, one role, seven days. A leaked token can be revoked in one call; the previous holder's session on other endpoints stops working immediately.
• Persistence: only the SHA-256 hash. No cleartext token ever hits disk. Recovery from loss = revoke + re-request.
• Rate limiting: the same email address cannot request more than one token per minute; the honeypot field silently drops obvious bots.
• Constant-time comparison: the verify path uses subtle::ConstantTimeEq so timing side-channels do not leak the hash.
• Auditability: every issue & revoke is a Quipu knot on ledger wallet 0x000000000000000000000000000000000000d005. Anyone can walk that string and reconstruct the complete history.
• Env-var fall-back removed: since 2026-08-14 the legacy static env vars are no longer honoured. An unknown or expired token yields the canonical 403 admin_token_invalid response regardless of what the operator has in their systemd unit file.

10. HTTP reference

Endpoint	Body / auth	Effect
POST /api/v1/admin-tokens/request	JSON { email, website }. Public.	Mint a fresh token if the email is eligible; email it. Rotates any active token for the same email.
POST /api/v1/admin-tokens/bootstrap	JSON { email, role, timestamp, signature, signer }. Founder Ed25519.	Same as /request but bypasses the domain / declaration eligibility check when a valid founder signature is supplied.
POST /api/v1/admin-tokens/revoke	JSON { token, reason } + X-Admin-Token.	Mark the target token as revoked. Anchored on-chain.
GET /api/v1/admin-tokens	X-Admin-Token.	Read-only listing of active records (hash prefixes only).

Every value in this document was verified live against the production endpoints on 2026-08-14. Issues or feedback: contact@datachain.one.