Profit Basetool — Exchange API

The Exchange API lets approved third-party applications exchange a member’s own data with the Profit Basetool: their blueprints, their stock, their ships, the anonymous open demand of their units, and drafts the member reviews in the browser. It is not a general-purpose API. Every client is approved publicly and case by case, and every member decides which client may do what.

At a glance #

Base URL	https://ingest.profit-base.online/exchange/v1
Sign-in	OAuth 2.0 device authorization grant against https://profit-base.online/auth/realms/iri, public client, no secret — authentication
Proof of possession	DPoP (RFC 9449, ES256) on every token request and every call
Formats	JSON Schema 2020-12, served at https://ingest.profit-base.online/exchange/v1/schemas/<name>.schema.json
Reference	OpenAPI reference · OpenAPI document · schemas
Errors	RFC 9457 problem+json with a stable code — error registry
Versioning	additive within v1 — versioning

Capabilities #

A capability is an OAuth scope. A request passes only when the route’s scope is in the token and the registry grants it to the client.

Scope	Allows
exchange.connect	the service document, labelling the installation, the account check
exchange.blueprints.read / .write	reading and changing the member’s blueprints
exchange.stock.read / .write	reading and setting the member’s stock lots, personal and shared
exchange.hangar.read / .write	reading and changing the member’s own ships
exchange.demand.read	the anonymous open demand of the member’s units
exchange.orgunits.read	the org units the member directly belongs to
exchange.orgstock.read	the shared warehouse stock of those units, one pool per unit
exchange.orgstock.details	with .read, the single named entries in the pools of units where the member is a Logistician
exchange.orgstock.write	booking stock into and out of the pools of units where the member is a Logistician, and those units’ rosters
exchange.drafts.blueprints / .refinery	staging blueprints or refinery orders for review in the browser

catalog/resolve and catalog/locations are open to any exchange scope.

Pages #

• Quick start — from the sandbox to a first synced blueprint in about fifteen minutes.
• Authentication — the device login, DPoP proofs, the server nonce, refreshing, disconnecting, and the DPoP reference implementation.
• Formats — item references, quantities, qualities, places, provenance, the offline file envelope.
• Errors — every code, its status and what a client does about it.
• Versioning — the stability promise and how the contract grows.
• Client security requirements — sign-in, DPoP, token storage, releases.
• Becoming an approved client — how to apply and what approval means.
• Local sandbox — the Basetool on your own machine, with a test client and synthetic members, to build and test a client against: requirements, test scenarios, troubleshooting.
• Conformance fixtures — valid and invalid examples for every schema.
• Sync guide — pull before push, baselines, tombstones, conflicts, idempotency, the mass-change guard, rate limits and back-off. Read it before writing a sync.
• Changelog — contract changes, dated.

Resources #

• Connect — the service document, labelling the installation, the account check.
• Catalogue — resolving item references, the warehouse locations.
• Blueprints — the blueprint feed and blueprint changes.
• Stock — stock lots, setting quantities, what a book-out does.
• Ships — the ship feed, links, upserts and removals.
• Org demand — the anonymous open demand of the member’s units.
• Org units — the org units the member directly belongs to.
• Org stock — the shared warehouse stock of the member’s units, and booking it in and out as a Logistician.
• Drafts — blueprint and refinery drafts reviewed in the browser.

Support #

Questions about an application or an approved client go to the issue tracker of krt-profit/basetool. Report a security problem privately as its security policy describes, never in a public issue.