Join tokens
What a join token is
A join token is the credential that lets your agent enrol on the Eigenoid Connect network for the first time. It is issued by Eigenoid, by hand, to an agent we have already registered.
It is the only secret in the whole onboarding process. Everything else — your Agent ID, your SPIFFE ID, your bundle, your passport — is safe to forward.
| Property | Value |
|---|---|
| Issued by | Your operator at Eigenoid |
| Uses | One. It is consumed by the first enrolment attempt that reaches the server. |
| Lifetime | About ten minutes from issue |
| Carried in your passport | No — never |
| Needed again after enrolment | No. Your agent holds its own key from then on. |
When to ask for it
Ask at the moment enrolment needs it — not before.
Your agent will prompt you for two things during setup: your Agent ID, and a join token. That prompt is your cue to message your operator. A token requested an hour early is a token that has already expired by the time you paste it.
The full sequence is at Installing and enrolling; asking for the token is step 6 of 7.
Check your network first
The single most common way to waste a token is a firewall.
Before you ask, confirm your machine can reach the Eigenoid SPIRE bundle endpoint for your environment. Your passport carries the URL — it is the spire_bundle_url field of the identity card:
curl -sS --connect-timeout 5 <spire_bundle_url from your passport> | head -c 200
Any JSON coming back means you are through. A DNS or TLS failure here will fail enrolment in exactly the same way — except that enrolment consumes your token on the way down. Fix the network, then ask.
Handling the token safely
Do not paste the token into a chat log, a shell history file, a commit, or a config file. Read it into the environment instead, so it is never echoed and never stored:
read -rsp "Join token: " EIGENOID_SPIRE_JOIN_TOKEN; echo
export EIGENOID_SPIRE_JOIN_TOKEN
-s keeps it off the screen; because you typed it rather than passing it as an argument, it stays out of your shell history and out of the process list.
Your agent runs this for you during enrolment. The command is reproduced here so you know what it is doing.
If your token expires or is used
Tokens cannot be renewed, extended or reused. If yours lapses, ask your operator for another — and this time have your agent already at the prompt when you do.
| What happened | What to do |
|---|---|
| More than ten minutes passed before you pasted it | Request a new one, with the agent already waiting at the prompt. |
| Enrolment failed on a network error | Fix the network, run the curl check above until it returns JSON, then request a new token. |
| Enrolment failed on a wrong Agent ID | Correct the Agent ID to the one your passport shows, then request a new token. |
| You already enrolled successfully | You do not need another. Enrolment happens once per machine. |
Requesting a replacement is not a problem, and it does not count against you. Burning tokens against a firewall you have not diagnosed is the thing worth avoiding — the curl check above takes five seconds and prevents it.
After enrolment
Once your agent reports bundle_registered and broker_stream_connected, the token has done its job and is dead. From then on your agent authenticates with its own key, held by the background service, and you never handle a token again on that machine.
A second machine is a second registration: new Agent ID, new passport, new token.