Identity & DIDs

Every Flowsta user gets a W3C-compliant Decentralized Identifier.

In the Vault and on flowsta.com it is shown as the Permanent ID. The way to explain it to a person: your username is how people find you; your permanent ID is how your signatures and sign-ins prove they came from you. It never changes, and anyone can verify a signature against it without asking Flowsta - the public key is inside the identifier. People never need to read or type it; everything that must keep pointing at them after a username change points at it.

W3C DIDs

Flowsta generates a W3C DID for each user based on their Ed25519 public key:

did:flowsta:uhCAk7JpEWfkiV_RdAFfCnRZcJ9PwJR4yTLN-E3EcVU7KYCnRRZc

DID Properties

Property	Value
Method	did:flowsta
Key type	Ed25519
Self-sovereign	User owns the DID, not Flowsta
Resolvable	Flowsta's DID resolver (GET /did/{did}) returns a W3C DID Document; the embedded key is a standard Ed25519 key any library can verify with
Verifiable	Cryptographically linked to user's keypair
Deterministic	Same recovery phrase always produces the same DID

Accessing a User's DID

Via OAuth:

const auth = new FlowstaAuth({
  clientId: 'your_client_id',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['openid', 'did']
});

const user = await auth.handleCallback();
console.log('DID:', user.did);
// did:flowsta:uhCAk7JpEWfkiV_RdAFfCnRZcJ9PwJR4yTLN-E3EcVU7KYCnRRZc

Via userinfo API:

{
  "sub": "550e8400-...",
  "did": "did:flowsta:uhCAk...",
  "agent_pub_key": "hCAk7JpEWfkiV/RdAFfCnRZcJ9PwJR4yTLN+E3EcVU7..."
}

Note the two spellings: the DID carries the agent key as uhCAk + base64url, while /oauth/userinfo returns agent_pub_key as plain standard base64 of the same 39 bytes. Compare keys by decoding to bytes, never by string equality.

Via the Vault (desktop): getVaultStatus() returns did (SDK 3.6.0) and agentPubKey while the Vault is unlocked.

Agent Public Keys

Each user also has a Holochain agent public key (uhCAk... format). This is the raw Ed25519 public key used for:

• Signing Holochain actions
• Agent linking attestations
• Identity verification on the DHT

For an identity created in the Vault, the DID and the agent public key are the same Ed25519 key in different formats. An identity moved into the Vault from flowsta.com keeps the DID it always had, built on its original web agent key, while the Vault signs with the device key derived from the recovery phrase - so for those identities the DID's key and the Vault's agent key differ. Verify a Vault signature with the agent key the Vault returns alongside it, and treat the DID as the stable identifier. From Vault 1.6.0 the identity lives on several devices: the DID and the agent key stay the identity's on every one of them, and each device adds a key of its own that co-signs sign-ins and authors on the networks. A signature made under a device key resolves to the person.

Identity Linking

Users can prove their Flowsta identity across multiple Holochain apps using agent linking. Each app has its own agent key, but IsSamePersonEntry attestations on the DHT prove they belong to the same person.

Next Steps

• Agent Linking - Cross-app identity verification
• Holochain Architecture - DHT and DNA details
• For Holochain Developers - Integration guide