> For the complete documentation index, see [llms.txt](https://docs.bosonnetwork.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bosonnetwork.io/getting-started/identity-app.md). # Manage Your Identity On Boson your identity is a key pair you hold, not an account a server holds for you. Something has to keep that key, use it when you approve what acts in your name, and never hand it over by accident. [**Boson Identity**](https://github.com/bosonnetwork/BosonIdentity) is the Android app that does this. It keeps your user key on the phone under the phone's own lock, and uses it to approve new devices, web sign-ins and your account's security. If you run a super node, it is also where you administer it. | I want to... | Where | | ------------------------------------------- | ---------------------------------------------------------------------- | | Hold an identity and approve things with it | This page | | Use Boson from an application I am writing | [Java SDK Setup](/build-applications/java-sdk.md) | | Run the node that hosts accounts | [Planning a Deployment](/deploy-a-node/planning.md) | | Understand what a key pair identity means | [Identity & Cryptography](/core-concepts/identity-and-cryptography.md) | {% hint style="info" %} An identity works without the app. Any Boson client can create and hold a key, and the super node never sees one either way. The app is the convenient place to keep the key you use every day, and the only thing today that can approve a web sign-in or enroll an administrator. {% endhint %} *** ## What you need | Requirement | Detail | | ------------- | --------------------------------------------------------------------- | | Android | 13 (API 33) or later | | A screen lock | Required. Keys are protected by the Android Keystore, which needs one | | A home node | Optional to start. Needed before your identity can use any service | Your *home node* is the super node that hosts your account and its services. It never sees your user key. You can create an identity first and join a node later. *** ## Install The app is not on an app store yet. Download the signed APK from the [releases](https://github.com/bosonnetwork/BosonIdentity/releases) page of the BosonIdentity repository, or build it from source. Each release publishes `boson-identity-.apk` and `boson-identity-.apk.asc`, a signature by the project's release key - the same key that signs the node packages: ``` BosonNetwork 5A01 2C93 0EED B923 B7AB 4739 A13B 99C0 C4AA 495A ``` ```bash gpg --keyserver hkps://keys.openpgp.org --recv-keys 5A012C930EEDB923B7AB4739A13B99C0C4AA495A gpg --verify boson-identity-.apk.asc boson-identity-.apk adb install boson-identity-.apk ``` *** ## Create or restore an identity On first run the app offers three ways to start: 1. **Create a new identity.** A fresh key pair, generated on the phone. 2. **Restore from a backup.** A key file, a QR code, or the key typed back in numbered rows. 3. **Move from another phone.** One scan and a code, which also retires the identity on the old phone. Back up the key before you do anything else. The app writes a backup as a file, a QR code, or numbered rows of groups, and then asks you to type some groups back to prove the backup is readable. Nobody can reissue this key for you. {% hint style="warning" %} A Boson user key cannot be reset. If you lose it with no backup, the identity is gone - the accounts and data under it with it. Passphrase recovery recovers an *account passphrase*, never the key itself. {% endhint %} One phone can hold several identities, and you can switch between them. *** ## Join a home node An identity on its own can be created and backed up, but it needs a home node before it can message, store objects or sign in anywhere. In the app, join one by scanning the node's QR code or entering its address. The node then admits you either through its proof of work - no invitation needed, the phone spends a little work instead - or as an existing member, if you already have an account there. After joining you can see the node's status and your plan, and edit your profile. The profile lives on the phone first and syncs to the node; publishing it as a public card lets anyone look you up by your ID, and the node's web gateway keeps announcing it while the phone is off. For what a home node is and what it does for you, see [Federation](/core-concepts/federation.md). *** ## Approve what acts in your name This is what the app is for. One **Scan** button reads every code it answers. | You want to | The other side shows | In the app | | ----------------------------- | --------------------------------------- | ----------------------------------------- | | Add a device to your account | A pairing code | Scan it, then approve | | Sign a web page in | A number, on the page | Scan, then pick the number the page shows | | Become a node's administrator | An enrollment code, on the node console | Scan, then confirm the number | **Devices.** The Devices tab lists the devices of your account and lets you rename or remove them. When you approve a new device, the user key goes to it only if it asks for one, and then sealed to its pairing code. A device that does not ask never receives the key. **Web sign-in.** A page offering "Sign in with Boson Identity" shows a number. You scan, pick that same number from the ones the app offers, and approve with your key. Picking the number is what stops a page you are not looking at from being signed in. **Administration.** An operator who runs `boson-director-cli user enroll-admin` gets an enrollment code on the console. Scanning it and confirming the number makes your identity an administrator of that node. See [Operator CLI Tools](/operate-a-node/cli-tools.md#enrolling-an-administrator). *** ## Keep the account safe The Security tab shows what needs attention, then each protection with its status. | Protection | What it is for | | ------------------ | ---------------------------------------------------------- | | Account passphrase | Guards account operations on the home node | | Recovery codes | Reset a forgotten passphrase | | Linked sign-ins | OAuth accounts that can also reset the passphrase | | Security log | Account events, with new ones marked until you review them | | Passkey backup | An opt-in copy of your key, for a new phone | A forgotten passphrase is reset with a recovery code, a passkey, or a linked OAuth account - never with the user key alone. See [Users, Devices & Subscriptions](/operate-a-node/users-devices-subscriptions.md#passphrase-recovery) for what the node does on its side. **How the key is protected.** The user key is sealed by an AES-256-GCM key in the Android Keystore, StrongBox where the phone has one, and every use asks for your fingerprint or screen lock. The phone's own device key stays usable for five minutes after you unlock it, so routine requests do not prompt each time. The key leaves the phone only when you say so: as a backup you make, sealed to a new device you approve that asked for one, or when you move the identity to a new phone. **Passkey backup** is off by default. It keeps a copy of the key in Google's Block Store, opened by a synced passkey on a new phone. It can only be turned on after you have made and checked your own backup, and it is never used to sign in. *** ## Administer a node from the phone An administrator gets a Dashboard in the app: the node's overview, users, plans, federation and blacklist. It runs in *admin mode* - a ten-minute session issued with your user key, which ends when you leave the page. Everyday administration belongs to accounts marked as administrators; the node's root user stays a break-glass credential for the console. The same screens are available in the browser on the node's Admin Dashboard. See [Web Interfaces](/configure-a-node/web-interfaces.md). *** ## For app developers Another app on the same phone can ask Boson Identity for an identity's home node, and ask it to approve the app as a new device of that identity. The user sees which app is asking and decides. No key or secret passes through these requests. The intents, extras and error codes are in [Asking Boson Identity from another app](https://github.com/bosonnetwork/BosonIdentity/blob/master/docs/app-requests.md). *** ## Next steps | | | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | See an app built on this | [Photon](https://github.com/bosonnetwork/PhotonMessenger), the messenger | | Build your own | [Hello Boson: Your First App](/getting-started/hello-boson.md) | | Run the node behind it | [Run Your First Node](/getting-started/first-node.md) | | Understand the identity model | [Identity & Cryptography](/core-concepts/identity-and-cryptography.md) and [Decentralized Identity (DID)](/core-concepts/decentralized-identity.md) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.bosonnetwork.io/getting-started/identity-app.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.