Visibility & access

V3 read endpoints return only what the calling identity is allowed to see. The same request can return a result for one caller and 404 for another. This page documents the rules so you can predict, per caller, whether an auction (and its items, bids, and purchases) will be visible.

Note

Visibility is enforced uniformly across the read surface — the discovery feed (/v3/auctions), auction detail (/v3/auctions/{id}), items (/v3/auction/{id}/items), item detail (/v3/item/{id}), and the bid/purchase history endpoints. An auction that is hidden from you is absent from the list and returns 404 on detail — there is no “exists but forbidden” 403 for a hidden auction. (Endpoints that act on a specific item you can’t access, e.g. favoriting, return 403.)

The model in one table

For a given caller, an auction is visible when it passes every applicable gate below. “Caller” is either anonymous (no token) or an authenticated user (bearer token); some gates further distinguish the caller’s relationship to the auction.

Auction trait	Anonymous	Authenticated (unaffiliated)	Registered bidder	Org owner / admin	Active org contact
Plain public	✅	✅	✅	✅	✅
Private fundraiser	✅	✅	✅	✅	✅
Invitation-code event	❌	✅	✅	✅	✅
Members-only whitelabel	❌	❌	✅	❌¹	✅
Test auction	❌	❌	✅	✅	❌²

✅ = listed + detail/items/bids/purchases return 200. ❌ = omitted from the list and 404 on detail. The columns are caller traits, not exclusive — a real caller may hold several (e.g. a registered bidder who is also an org contact).

• ¹ A members-only whitelabel grants access via an active org contact or a direct registration — not via an org-admin role alone.
• ² A test auction is visible to a registered bidder or an org owner/admin, not to a plain org contact.

The gates

Public auctions

The default. Anyone — including anonymous callers — can read a public auction, its items, and their bid/purchase history. These responses are identity-free and edge-cacheable.

Private fundraisers

A “private fundraiser” suppresses the donor leaderboard / ranking display. It is not an access gate: the auction, its items, and bid/purchase history remain readable under the normal public rules. If you previously relied on a private fundraiser hiding its auction or bids from anonymous callers, that was never the intended behavior and is not how V3 behaves.

Invitation-code events (“Make Event Private”)

An event protected by an invitation code is hidden from anonymous callers — it is omitted from the feed and returns 404 on detail/items/item/bids/ purchases. Any authenticated caller (any valid bearer token) can read it.

The invitation code itself is a client-side convenience (an offline-shared code that the app uses to drop a “members only” splash screen). The API does not validate the code and does not require it; the server-side rule is simply no anonymous access. If your integration needs to read an invitation-code event, authenticate first.

Members-only whitelabels

Some whitelabels are configured so their auctions are visible only to people affiliated with the organization. For these, a caller must be registered on the auction (a bidder relationship) or be an active, authorized contact of the organization. Anonymous and unaffiliated authenticated callers get 404.

Test auctions

Test auctions are for QA and setup and are hidden from the public. They are previewable only by:

• the organization owner or an organization admin, or
• a registered bidder on that test auction.

Anonymous callers and unaffiliated authenticated users get 404. This applies consistently to the list, detail, items, item/bids/purchases, and the bidder rails (e.g. a registered bidder’s own test auction appears in /v3/bidder/my-auctions).

How to gain access

You need to read…	Authenticate?	Additional requirement
A public auction	No	—
A private fundraiser	No	— (only the leaderboard is suppressed)
An invitation-code event	Yes	Any valid token
A members-only whitelabel auction	Yes	Be registered on the auction, or an active org contact
A test auction	Yes	Be an org owner/admin, or a registered bidder on it

“Registered on the auction” means you’ve joined/registered as a bidder (the same relationship that assigns you a paddle). See Authentication for obtaining a token.

Why a result disappeared

If an auction or item you could see before now returns 404, the most common causes are:

• the caller is anonymous and the auction is an invitation-code event, members-only, or a test auction;
• the auction moved to a non-visible status (e.g. setup/archived);
• the caller’s registration or org contact was removed.

Visibility is re-evaluated per request, so access can change as registrations, auction status, or whitelabel configuration change.