Authentication

Authenticate with a Bearer token:

curl "https://app.bidvise.com/api/v2/items" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

Every request needs one. There is no unauthenticated part of the API.

Keys

An API key is created in the Bidvise backoffice and belongs to exactly one auction house. Treat the key as an opaque string: store it as a secret, send it unchanged, and do not parse it.

Permissions

A key carries a role, and the role decides which resources the key may touch. Permissions are granular: they are granted per resource and per action, as resource.action: auctions.read, lots.read, and so on. The same vocabulary governs staff accounts in the backoffice, so a key can never be granted something a person could not be.

Give a key the narrowest role that does its job. A reporting integration that only needs the catalogue gets auctions.read and lots.read; it cannot reach anything else, and it will not silently gain access when new endpoints ship.

If no role is chosen, the key inherits the access of the account that created it. That is convenient for a first integration and wrong for anything long-lived: a key created by an owner account can do everything the owner can.

Every endpoint in this reference states the permission it requires. Calling one without it returns 403:

{
  "type": "https://docs.bidvise.com/api/problems/forbidden",
  "title": "Insufficient permissions",
  "status": 403,
  "detail": "This API key does not have the lots.read permission."
}

Item writes require both lots.write and lots.read, because the response returns the item. Attaching existing sellers/categories also requires seller_profiles.read/categories.read, respectively; their write permissions are not required.

What a key can see

The key is the scope. Every response is filtered to the house the key belongs to, and no parameter widens that.

A lot belonging to another house is reported as 404 Not Found, not 403 Forbidden: the difference matters, because a 403 would confirm that the object exists. Whether another house has a lot at a given ID is not something an API key should be able to learn.

Keeping a key safe

Keys are secrets. Keep them on your server, in your environment or secret store: not in a browser, a mobile binary, or source control. Anyone holding the key can read the whole catalogue it is scoped to.

If a key is exposed, revoke it in the backoffice; revocation takes effect immediately. To rotate without downtime, create the new key, deploy it, then revoke the old one: both work during the overlap.

Errors

A missing or unknown key returns an RFC 9457 problem document:

{
  "type": "https://docs.bidvise.com/api/problems/unauthorized",
  "title": "Missing credentials",
  "status": 401,
  "detail": "Provide your API key as: Authorization: Bearer <key>"
}

A key that is valid but not linked to a house returns 403. See conventions for the error shape in general.