Davi Developers LogoDavi Developers

Documentation

Fetching a Card

Read a card's public identity document, or list the cards a signed-in user holds.

This page shows you the two ways to read a card:

  • The card document is public. It needs no token, API key or account, and tells you who holds the card and who issued it. A card's own URL leads to it.
  • The card API needs a user access token with card:read, and lists the cards the signed-in user holds.

Use the document unless you specifically need the signed-in user's own cards.

The public document

Every card publishes a JSON document at a stable URL:

curl -H "Accept: application/vnd.davi.card+json" \
  "https://davi.social/c/CARD_UID/json"

It carries the holder's display name, avatar, public links and profile URL, the issuing organization, and the card's status. It sends Access-Control-Allow-Origin: *, so a browser can fetch it cross-origin.

If you have a card page or profile URL instead of the document URL, fetch the page and follow its rel="alternate" link to the document.

Card JSON Format has the full field list and transport contract.

The cards a user holds

curl "https://api.davi.social/api/v1/cards" \
  -H "Authorization: Bearer ACCESS_TOKEN"

GET /cards (scope card:read) lists the caller's own cards, and GET /cards/{card_uuid} reads one of them. Another user's card returns 404, the same response as a card that does not exist.

Cards are addressed by UUID, not by slug. This is the exception to slug addressing. A card's identifier is printed on a physical object, so it must not change when its holder renames anything.

Check status, not the fields

Read status (claimed, unclaimed or frozen) to decide whether a card is live. Do not infer it from which fields are present. A frozen card still carries its holder's details: freezing withholds the card as a credential, not the holder's identity. This applies to both the document and the API.

Next