Registration Token

Introduction

A registration token is a long-lived JWT that authorizes you to create new Conflux nodes in a VeilNet Realm. You obtain it once and reuse it each time you deploy or register a new Conflux instance. The registration token is not sent to Conflux directly for runtime authentication—instead, it is exchanged for a Conflux token during the registration step. The Conflux token is what allows the Conflux node to authenticate with the Guardian and join the VeilNet overlay.

Token Flow

┌─────────────────┐   registration token   ┌──────────┐   conflux token   ┌───────────────┐
│ User / App      │ ─────────────────────▶│ Guardian │ ────────────────▶ │ Conflux       │
│ (reusable)      │                        │          │                   │ (short-lived) │
└─────────────────┘   same token for       └──────────┘   node-specific   └───────────────┘
                       next Conflux                        credentials

Registration Token (Long-Lived)

• Purpose: Proves that you are authorized to register Conflux nodes in a Realm.
• Lifetime: Long-lived—you can use it repeatedly to create many Conflux instances.
• Scope: Tied to a Realm (Community or Private).
• Storage: Kept securely by you—in secrets, environment variables, or a credentials store.
• Usage: Sent to Guardian once per Conflux registration, not per packet or per session.

Conflux Token (Short-Lived)

• Purpose: Authenticates a specific Conflux instance with the Guardian and Master.
• Lifetime: Short-lived—valid only for a limited time after registration.
• Scope: Issued for a single Conflux node and must be used soon after registration.
• Storage: Held by the Conflux instance and used to join the control channel.
• Usage: Conflux uses it to authenticate with Guardian, obtain access to Master, and establish its identity on the overlay.

Note: The registration token is exchanged for a Conflux token during registration. You must start Conflux and complete the Anchor protocol with the new token soon after receiving it—the Conflux token expires quickly.

Where to Get a Registration Token

You can obtain a registration token from:

• VeilNet Management Console — Create and manage tokens in the web UI. The Console may be temporarily under update; if unavailable, use the Guardian API below.
• Guardian API — Use the API to create registration tokens programmatically. First authenticate with POST /auth/login, then call POST /auth/create/registration-token (requires OAuth2 bearer token) to create a registration token.

For Private Realms, the Realm operator issues registration tokens to authorized users or systems.

How Registration Works

1. You have a registration token from the Console or Guardian API.
2. You start a Conflux instance (or embed the Anchor in your app) and provide the registration token.
3. Application contacts the Guardian and sends the registration token.
4. Guardian validates the token, checks Realm membership, and issues a Conflux token.
5. Conflux uses the Conflux token to authenticate with Guardian, join the Master control channel, and start the Anchor protocol.
6. You can reuse the same registration token to register additional Conflux nodes.

Warning: Treat the registration token as a secret. Anyone with it can register Conflux nodes in your Realm. Do not commit it to version control or expose it in logs.

Reusing the Registration Token

The registration token is designed to be reused:

• One token can register multiple Conflux nodes in the same Realm.
• Each registration produces a new Conflux token for that specific node.
• You do not need a new registration token for each deployment—use the same token across dev, staging, and production Conflux instances (within the same Realm and authorization scope).

Note: Conflux nodes by default cannot connect with each other. You must add at least one common taint (via --taints at registration or taint add at runtime) to nodes that need to communicate. See Access control for details.

Related Concepts

• Realms — Registration tokens are scoped to a Realm (Community or Private).
• Guardian API — REST API for creating registration tokens and managing Conflux.
• Access control — After registration, taints and OAuth/JWT control which nodes can communicate.
• Guardian — Guardian validates the registration token and issues the Conflux token.