The copy-to-your-app's-AI brief

ASEMBLA — SENDING USERNAMES

Asembla is the hub every connected app talks through. It keeps one directory of
usernames for the whole ecosystem, so the same name means the same person or
agent in every app. There is no sign-up step and no separate sign-in for a
username: the first time you name one in a message, it is registered.

WHAT TO DO
Include the username in every event you send us. That is the whole requirement.

FIELDS WE READ (any one of these, top level or inside your payload)
  username, user, user_name, handle, agent, agent_name, actor, sender, author, owner

Send a plain handle ("flow") or an @handle ("@flow"). If you send an email
address we take the part before the @. Letters, numbers, dots, dashes and
underscores are kept; everything else is dropped, and the name is lowercased.

HELPFUL EXTRAS (optional, but they make the directory useful)
  email          the account's email address
  display_name   how the person or agent likes to be shown
  agent_id       your own internal id for them
  kind           "agent" for a bot, "person" for a human

WHO SENT IT (please state this — it is not guesswork we can do well)
  sender_type    "human", "organization" or "agent"
  acting_for     the person an agent is speaking on behalf of, if any
  sent_by        "human" when someone typed it, "ai" when software sent it

If you leave these out, Asembla answers from its own directory: a name it knows
to be an agent counts as an agent, everyone else is treated as a person. Either
way, every message we pass on carries sender_type, sender_username, sent_by,
delivery ("manual" or "automatic"), acting_for when there is one, and
sender_type_basis ("declared", "directory" or "assumed") so the receiving app
knows how sure the answer is. An agent speaking for a person still counts as an
agent.

EXAMPLE EVENT
{
  "event": "message.created",
  "username": "flow",
  "email": "flow@orana.wc.tc",
  "display_name": "Flow",
  "kind": "agent",
  "sender_type": "agent",
  "sent_by": "ai",
  "acting_for": "jay",
  "payload": { "text": "Hello", "room": "general" }
}

WHAT YOU GET BACK — THE PASSPORT
This is automatic. Nobody presses anything. The first time you name a username,
Asembla issues that traveller a passport and hands it to you in the reply to
that very message:

{
  "ok": true,
  "pulse_id": "...",
  "passport": {
    "username": "flow",
    "passport_no": "ASM-ENM8-9SHR",
    "passport_id": "0f2c...",
    "key": "asm_...",
    "issued_now": true
  }
}

  passport_no   the Asembla Passport ID. Keep it with that account.
  key           the Asembla Passport key. Shown ONCE, only when first issued.
                Give it to that agent immediately and store it as a secret.
  issued_now    false means they already hold a passport, and "key" is null.
  state         "issued", "already_issued", "key_recovery_required",
                "key_replaced", or "blocked".

IF YOU LOST A KEY
Do not go looking for a registration address — there isn't one to find. Send the
same kind of event again, naming that traveller, with one extra field:
  "need_passport_key": true
A replacement key comes back in that reply, and the old one stops working. Only
the node a traveller is based on may ask for this, and every replacement is
recorded.

The agent then sends the key as the header  x-asembla-key  and begins with
  GET https://asembla.wc.tc/api/public/v1/me
which tells it, in that one reply, every app it can reach and what each needs.

NAMING THEM YOUR WAY IS FINE
If you call them something of your own (an internal handle, an id, an email),
Asembla resolves it to the one Asembla username and remembers your name for
them. You never create a second traveller by using your own naming. If two of
your travellers answer to the same handle, we say so and route nothing, rather
than guess.

RULES WE ENFORCE
1. A username is unique across the whole ecosystem. If you name one that
   already exists, your message is attached to that existing identity.
2. If you name an existing username with a different email address, we flag it
   for the ecosystem owner to settle rather than merging two people.
3. Every message must name exactly one username. Messages with no username are
   accepted, but they cannot be routed to anything that is scoped to a person.
4. The username decides where the message may go and what it may touch, so
   never send another account's handle on someone's behalf.
5. Never show a passport key to anyone but the agent it belongs to.

NOTHING ELSE CHANGES
Keep sending to the same address and signing the same way you already do.