Davi separates what a thing is from who holds it right now. That separation shapes most of the API.

The picture

The four nouns

• A User owns one or more wallets: a personal primary wallet, plus a membership wallet for each organization they join.
• A Wallet is a points/rewards ledger account. One or more cards can tap into it.
• A Card is a tap-able credential (NFC, QR, or virtual). It points at exactly one wallet, and whoever owns that wallet owns the card. Issuing a card is separate from owning it.
• An Organization issues cards (branding, membership tier, freeze) and can run its own treasury wallet.

A Profile is a public identity page. The user owns it, as a sibling of their wallets, and a card routes to one when tapped. Profiles are not attached to wallets.

Registry vs. assignment

A card has two layers:

• The registry: the stable set of valid, registered cards and their issuance configuration (identifier, card type, issuing organization, the membership tier granted on claim, and design). It is never personalized and never moves.
• The assignment layer: where a card is held right now (which wallet owns it, its custom name and image, its profile route, and holder-level freeze). Transferring a card re-points only this layer; the registry entry is untouched.

Because of this split, ownership is always derived through the wallet:

card → connection.wallet → wallet's owner (user)

The assignment layer has no owner fields of its own, so ownership cannot drift out of sync.

Wallet kinds

A wallet's kind is determined by its owner, not by a type field:

How things resolve

• Card owner: card → connection.wallet → wallet's user. Empty for unclaimed inventory or bearer wallets.
• Effective frozen: a card is frozen if either the registry (org) freeze or the holder-level freeze is set. The registry freeze is dominant and the holder cannot clear it.
• Profile shown on tap: the card's profile-route override if set, otherwise the owner's primary profile.

Card lifecycle

Each step is a distinct operation:

• Mint (fulfillment): create the registry entry for a manufactured card. A physical card's identifier is burned into hardware before Davi hears about it, so only fulfillment can mint, and nothing else creates an identifier. That is what makes an unknown identifier refusable.
• Assign (organization): take an already-minted card into the org's inventory and set its issuance config. Release is the reverse, and is refused once someone holds the card.
• Provision (user/virtual): create a virtual card plus its wallet binding. This happens automatically at signup.
• Claim: bind the card to a wallet the user owns, keyed on the identifier (all a caller has after a tap). If the card carries a membership tier, claiming it also creates an organization membership. If its card model has a profile template, a profile is generated.
• Unclaim: unbind the wallet. For a physical or org-issued card the registry entry is kept, because the identifier belongs to the object, and the card becomes claimable again. A self-provisioned virtual card, which nobody else can hold, is destroyed.
• Freeze: two independent flags, the issuer's and the holder's. The effective state is the OR of the two, so a holder cannot clear an issuer's freeze.

Transfer is not an operation. The model supports it (re-pointing the assignment layer moves a card without touching the registry), but no endpoint exposes it. To hand a card to someone else, unclaim it and they claim it.

Organizations and org-scoped tokens

Most resources belong to an organization: memberships, activities, rewards, reward triggers, and webhooks. An entity with no organization is platform-owned, for example a freely claimable platform card.

To act on an organization's resources, your app uses an org-scoped token. It carries the organization's context and the user's staff role within it (owner, manager, or member). Endpoints marked "Requires an org-scoped token" in the reference are gated on it. See Acting as an Organization.

Keep going

• Glossary: every term in one place.
• Authentication Model: how tokens work.