Skip to main content
This guide takes an organization from nothing to owning an agent on T3N: a did:t3n DID the organization controls, with an agent card that T3N hosts privately for the organization to manage — never public unless the organization chooses. Every step uses the t3n CLI that ships with the @terminal3/t3n-sdk package — no code required, for the whole lifecycle: create, read, and update (updating needs CLI 4.25.0 or newer; older installs have an SDK fallback).
Onboarding, not permissions. This page gives an agent an identity and a card. It does not grant the agent access to anything — no user data, no contract functions. That’s a separate step the data owner performs afterwards: see Agent Auth.Two onboarding paths. This is the one where an organization owns the agent, with a card kept private by default. If instead an agent registers itself — public and discoverable — see Register a Public Agent.
The flow is:
  1. Download the SDK
  2. Get an org admin’s key
  3. Create your organization
  4. Scaffold the agent card
  5. Provision the agent
  6. Read the card back
All commands that talk to the network accept --env sandbox|testnet|production (or the T3N_ENV environment variable); sandbox and testnet are the same test network. testnet is the default — the examples below pass it explicitly anyway, so a copied command never depends on your shell.
1

Download the SDK

The CLI is part of the TypeScript SDK. You can run it with zero install, or install it globally:
The rest of this guide uses the global t3n form; substitute npx @terminal3/t3n-sdk if you skipped the install.
2

Get an org admin's key

The organization admin’s key is a standard Ethereum-style secp256k1 private key (32 bytes, 0x-prefixed hex). The easiest way to get one is the claim page — it issues a key together with metered test credits, and provisioning is a write operation that consumes credits.Put the key in your shell’s environment; every signing command reads it from there (or from --api-key):
Give the admin its own key and keep it out of source control. Every command below is signed by this key, so whoever holds it controls the organization and the agents it owns.
3

Create your organization

Skip this if your organization already exists — just use its DID. Otherwise create one; the authenticated caller becomes its initial admin:
Drop --json for human-readable output (organisation created: did:t3n:0a1b2c...) if you’d rather copy the DID by hand.
org create is not idempotent — every call mints a new organization. Run it once and keep the DID; re-running it because you lost the DID leaves an orphan org behind.
4

Scaffold the agent card

The agent card is a JSON document, following the ERC-8004 registration format, that describes the agent and lists its service endpoints — including its A2A agent card. Scaffold one with:
Run interactively, it walks you through name, description, image, and which services to include (A2A / MCP / DID). In scripts it falls back to flags: --name, --description, --image, --did, --x402, and --force. Replace the placeholders with your agent’s real endpoints and keep the whole card under 16 KiB.
This step is optional — skip it to let T3N host a minimal default card for the agent instead (shown in the next step).
5

Provision the agent

Mint the agent and host its card, all in one transaction. You don’t need a URL for the card — T3N serves it at /api/agent-card/<did>:
One transaction mints the agent’s DID and its wallet, and hosts the card privately under the organization. Nothing is published — the agent is not publicly discoverable, by design.
The API key is printed exactly once and cannot be recovered. Store it now — it is the agent’s own credential, what the agent uses to authenticate as itself.The agent’s secp256k1 key is minted inside the TEE and never leaves it; you never see a private key. What you get instead is an opaque bearer token, t3n_key_<key-id>.<secret>, of which only a hash is stored on-ledger — which is why it is unrecoverable rather than merely inconvenient to look up. The agent presents it verbatim in the X-T3N-Api-Key header of a stateless POST /api/invoke.Scripting? Use --json and capture .apiKey, plus .keyId (the 16-hex lookup id, safe to log and to store alongside your records — the secret half is not).
Drop --card to host a default card. t3n agent create --org "$ORG_DID" --name "Booking Bot" (nothing else) hosts a minimal default card, named after the agent, with its DID as the service entry:
Pass --no-card to mint the agent with no card at all — add one later with card-set, which needs the writer grant covered in the last step. And pass --uri <url> only if the agent also has its own external endpoint you want recorded in its DID document (an agent-uri service entry is added for it).
6

Read the card back

The card lives in your organization’s private scope. Read it back as an org admin — no publishing required:
Only the organization’s admins — or a principal you grant a delegation credential to — can read it. It is not exposed at the public /api/agent-card/<did> endpoint.That’s the whole lifecycle for a private org agent — create, read, update — all authenticated, none of it public. If card-get returns your card, you’re done; updating it takes the one extra grant below.
Updating the card needs one more grant. t3n agent card-set --owner "$ORG_DID" --agent "$AGENT_DID" --file agent-card.json fails for a freshly created org with:
This is by design, not a bug: org-data keeps two roles separate — admins manage policy, writers manage data — and being an admin does not imply write access to any scope. The card you just read was written by the contract during agent create, not by you.To write it yourself, add your own DID to the agent-cards scope’s writer list. One call, once per scope:
card-set then succeeds, and card-get returns the updated card. Check the list any time with t3n org writers-get --org "$ORG_DID" --scope agent-cards.
The writer verbs need @terminal3/t3n-sdk 4.25.0 or newer (npx @terminal3/t3n-sdk always runs the latest; a pinned older install won’t have them). On an older CLI, grant it from the SDK — but setWriters replaces the list, so read it first and merge, or you will revoke every other writer on the scope:
Granting and revoking write access. writers-add and writers-remove adjust the list and leave the other writers alone — the usual choice. writers-set replaces the whole list, so anyone you omit loses access; writers-clear removes everyone, leaving the scope unwritable until you grant again. All four require an org admin.add and remove read the current list and write back the result, so two admins editing the same scope at the same moment can overwrite each other. That’s fine interactively; scripts that might race should use writers-set with the full intended list.
Reads are metered too. If card-get returns InsufficientCredit, the account is simply out of credits — top up and retry; nothing is wrong with the card. Metering settles after the fact, so the writes in earlier steps can succeed and then leave the balance short for this read.
Publishing for public discovery (optional). To list the agent publicly — resolvable by anyone, without a key, at GET /api/agent-card/<did> — publish it explicitly: t3n agent card-publish --owner "$ORG_DID" --agent "$AGENT_DID". Consent is already in place (the agent was minted with your organization linked), so it’s a single call, reversible with card-unpublish. Most org-internal agents never need it.
The card is ordinary org-data: create/card-set store it in your organization’s agent-cards scope on the built-in tee:org-data/contracts TEE contract, at a deterministic entry id derived from (orgDid, agentDid). Reads (card-get) go through org-data’s normal authorization — an org admin, or a holder of a delegation credential scoped to that read. It is never copied to the world-readable card map unless you explicitly publish it.

​
What’s next

  • The agent now has an identity and a card. Next, let it actually do something — granting permission to act on users’ data and contracts → Agent Auth and Delegate Access
  • How DIDs work on T3N → Decentralized Identifiers
  • Provisioning and card writes consume credits → Tokens