| 1 | --- |
| 2 | title: SIWE Authentication |
| 3 | description: How Portal uses SIWE for tunnel registration and local agent wallet status access. |
| 4 | --- |
| 5 | |
| 6 | # SIWE Authentication |
| 7 | |
| 8 | Portal uses Sign-In with Ethereum (SIWE) in two places: |
| 9 | |
| 10 | - tunnel registration, signed automatically by the local tunnel identity |
| 11 | - optional browser wallet login for local agent status access |
| 12 | |
| 13 | For the full operational guide, see [Wallet and ENS](/wallet-and-ens). |
| 14 | |
| 15 | ## Tunnel Registration |
| 16 | |
| 17 | `portal expose` and `portal agent` create or load a local secp256k1 identity |
| 18 | from `identity.json`. During registration, the relay returns a SIWE challenge |
| 19 | with statement `Register a portal lease`; the tunnel signs it with the local |
| 20 | identity private key and receives a lease access token. |
| 21 | |
| 22 | `identity.json` can store the signing key directly as `private_key`, or store a |
| 23 | BIP-39 `mnemonic` with `derivation_path` and let Portal derive the key at load |
| 24 | time. |
| 25 | |
| 26 | This flow is automatic. It does not require a browser wallet. |
| 27 | |
| 28 | ```bash |
| 29 | portal expose 3000 --name myapp |
| 30 | ``` |
| 31 | |
| 32 | There is no `--auth siwe` flag. SIWE is part of the normal registration |
| 33 | protocol. |
| 34 | |
| 35 | ## Agent Wallet Status Access |
| 36 | |
| 37 | Relay admin access uses `ADMIN_TOKEN`, not SIWE. |
| 38 | |
| 39 | The local agent also exposes `/agent/auth/*` wallet endpoints. Agent wallet |
| 40 | sessions can read `/agent/status`; tunnel mutations still require the local |
| 41 | bearer token stored in the agent state directory. |
| 42 | |
| 43 | ## ENS |
| 44 | |
| 45 | Portal does not use ENS names as tunnel names. Tunnel names are single DNS |
| 46 | labels such as `myapp`. |
| 47 | |
| 48 | Relay operators can optionally enable ENS gasless DNS import. In that mode, |
| 49 | Portal manages DNSSEC and `ENS1 ...` TXT records for the relay domain and lease |
| 50 | hostnames so ENS-aware clients can resolve them to Portal identity addresses. |
| 51 | |
| 52 | ## Next Steps |
| 53 | |
| 54 | - [Wallet and ENS](/wallet-and-ens): detailed wallet and ENS behavior |
| 55 | - [Security Model](/security-model): encryption and identity boundaries |
| 56 | - [Configuration](/configuration): full configuration reference |