Signing identities

One bunker, several identities

One bunker can sign as several Nostr keys, its identities. An agency, or a brand with several accounts, needs one bunker, not one per key.

  • The key you imported first, when you installed Bancwr, is the primary.
  • Each connection token is issued for one identity. Its app signs, encrypts and decrypts only as that identity.
  • Administrators choose which identities each member may sign as.

With only one identity, nothing changes, and none of this appears in the console.

Adding an identity

Identities are added on the server, never in the console, so a key never passes through a browser.

  1. Put the new key, as an nsec or in hex, in a file, and hand it to the bunker's user:
    (umask 077; ${EDITOR:-nano} secrets/brand_b)
    chmod 400 secrets/brand_b
    
    # Rootless Podman
    podman unshare chown 65532:65532 secrets/brand_b
    
    # Docker
    sudo chown 65532:65532 secrets/brand_b
    
  2. Add it, with a label to recognise it by:
    podman compose run --rm --no-deps \
      -v ./secrets/brand_b:/run/secrets/brand_b:ro,Z \
      -e BUNKER_NSEC_FILE=/run/secrets/brand_b \
      bunker import-key --add --label "Brand B"
    

    With Docker, use docker compose in the same command. It prints the new identity's npub, never its key.
  3. Delete every plain copy of the key, as after the first import:
    # Rootless Podman
    podman unshare rm secrets/brand_b
    
    # Docker
    sudo rm secrets/brand_b
    
  4. Restart the bunker. A new identity loads when the bunker starts. Until then, Config, Identities shows it as Loads when the bunker restarts.
    podman compose restart bunker
    

The import refuses a key that is already an identity, the primary, or a team member's key.

Each identity is encrypted under the same root credential as the primary, and kept in the bunker's database, so every backup carries them all. See Protecting the bunker key.

The Identities list

Config, Identities lists the identities the bunker signs as, with each one's label and npub. The primary is marked.

  • To rename an identity, edit its label. A label is 1 to 100 characters.
  • An identity cannot be removed yet. If one is no longer used, rename it to say so, and revoke its connections.

Granting identities to members

Once the bunker holds more than one identity:

  • A signer needs a grant for each identity they may sign as, the primary included.
  • Administrators may sign as every identity, with no grant needed.
  • Viewers sign as none.

When you add the first identity beside the primary, every member who could sign keeps the primary, so nobody loses access.

To grant or remove identities:

  1. Open Team and click the member's name.
  2. Under May sign as, tick the identities they may sign as, and untick the ones they may not.

When you add a member, the same choice appears on the Add Team Member form, with the primary ticked.

Removing a grant disconnects the member's apps for that identity, and revokes their unused tokens for it. Their other identities are untouched.

Which identity an app signs as

When an administrator issues a connection token under Connections, Sign as chooses the identity. Only identities the member may sign as are offered. Without a choice, the token is for the primary.

  • The token's bunker:// string names that identity's public key. See The connection string apps use.
  • The app signs, encrypts and decrypts only as that identity.
  • An app connected to one identity that sends a request to another is refused.
  • A token for one identity cannot be used to connect to another. The token is used up.

Every identity uses the bunker's relays. The bunker listens for requests to all of them on the same relays.

In the logs

The signing log names the identity that signed, in the Signed as column. The export carries it too. See The Logs page.

If an identity cannot be unlocked

At start, the bunker decrypts the primary, then every other identity. If any does not decrypt to its recorded public key, because its row was altered or the root credential is wrong, the bunker stays locked and its status names the identity by its label. Nothing signs until it is fixed: restore the database from a backup. See When the bunker will not sign.

Known limits

  • An identity cannot be removed yet, only renamed.
  • Every identity shares the one root credential, in the one process. Whoever controls the server has them all. Run separate bunkers for keys that must not share that fate.