Authentication and scope
Registered confidential HTTP integrations and person-delegated MCP access use current Vault authority.
HTTP callers
A signed-in person may call customer routes with the Vault session established by the console. A registered confidential integration may use HTTP Basic credentials. Its server-verified external subject maps to a real Vault person; the request cannot choose an arbitrary user ID. Provisioning is arranged with Stashtab. Keep the client secret server-side and never copy it into a browser.
curl --user "$CLIENT_ID:$CLIENT_SECRET" \
"$VAULT_BASE_URL/v1/organizations/$ORG_ID/inventory?limit=50"
$VAULT_BASE_URL is the Vault host supplied for the integration. The path’s
organization ID selects a customer; it does not grant access. Vault checks the
person’s current membership and the integration’s current binding on each call,
including receipt reads. An unknown or inaccessible organization is not
disclosed through a successful response.
Organization API keys
Organization Owners and Admins manage organization-owned API keys in Vault Settings. Vault shows a newly created or rotated secret once. Store it outside the browser and send the standard bearer credential over either HTTP or MCP:
curl \
--header "Authorization: Bearer $VAULT_ORGANIZATION_API_KEY" \
"$VAULT_BASE_URL/v1/organizations/$ORG_ID/orders?limit=50"
Organization API-key values begin with vak1.. They are scoped to one
organization, one immutable mode and either Read-only or Read/write permission.
The path organization ID cannot broaden that scope, and revocation takes effect
on the next call. The key remains valid if its creator later leaves the
organization; current key revocation prevents its next call. A key never grants
staff, team-administration, key-management or native protocol authority.
Read-only keys can read ordinary orders and their current status/tracking, including bounded batches of known orders, catalog and inventory, purchase orders and their previews, the opening feed, recorded operation outcomes, and configured parcel-shipping quotes. They can preview a published pack or selected source card ordinals in their verified Live deployment. They can also read the scoped partner-event stream, subscriptions and delivery outcomes. Read/write keys add ordinary order creation, held-order updates, explicit release, customer-label changes, purchase-order declarations, eligible deposit declaration corrections, redemption creation, receiver subscription creation/revocation and bounded named notification replay. The generated reference marks each operation that accepts an organization API key; current business preconditions still apply to every admitted request.
Integration capability matrix
Use a Read-only key for reads and a Read/write key for mutations. Both key types remain restricted to their organization and immutable mode. This matrix describes application behavior; Stashtab supplies the released host and current environment configuration for the integration.
| API surface | Key permission | Live behavior | Configured Test behavior |
|---|---|---|---|
| Catalog and inventory list, detail and export | Read | Current scoped catalog and verified stock facts | Current Test catalog and simulated stock |
| Product configuration and opening feed | Read | Scoped configuration and recorded openings | Unavailable; the request cannot read Live |
| Parcel shipping quotes | Read | Configured provider estimates and eligible selections | Configured Test estimates; no provider shipment or label |
| Ordinary order creation and changes | Read/write | Existing submission, hold and release policies | Scoped Test records and simulated outcomes |
| Individual and batch order reads | Read | Permitted recipient, status and tracking facts | Current Test orders only; old or foreign orders are missing |
| Published whole-pack and selected-card preview | Read | Recorded conditions and frozen source revision/digest within the verified deployment and revealed opening | Requires Live mode |
| Explicit-line redemption creation | Read/write | Positive address validation, scoped stock and current shipping review; starts On hold with a server-owned cancellation deadline | Real address validation, configured raw-card or sealed-item lines and simulated stock reservation |
| Ordinary PO preview, declarations and corrections | Read for preview; Read/write for declarations | Current declaration, binding and revision policy | Current Test declarations and revisions |
| PO list, detail, export and recorded deposit results | Read | Scoped declarations, counts, assessment and acceptance | Current Test records; player-deposit label creation is unavailable |
| Deposit dispute list and event feed | Read | Scoped disputes and durable checkpoints | Current Test disputes and events |
| Operation receipts | Read | Customer-safe recorded outcomes | Current Test receipts |
| Partner event, subscription and delivery reads | Read | Scoped facts and delivery outcomes | Scoped facts and capture outcomes |
| Subscription creation/revocation and delivery replay | Read/write | Configured signed HTTPS delivery | Private Test captures; no receiver acknowledgement |
Native protocol operations retain their separate credential and authority. An organization key cannot administer a team or keys, impersonate staff, mint tokens, or use a native protocol identity. A Test capture, estimate or simulated outcome does not establish provider or receiver acceptance.
The quote operation is a read: it returns separated shipping, fulfillment and
applicable-fee estimates plus an eligible selection. It prices one parcel at
the order’s total weight and offers only services of the warehouse’s
configured carrier account; overnight services are not offered. A quote caller supplies
that selection to ordinary or redemption creation, where Vault checks it again
just before the native create. Existing API callers may still create an unquoted
ordinary order for legacy compatibility. The browser New order flow instead
requires a current priced selection before Create order; an incomplete
preparation can be saved as a draft. An API or MCP ordinary create starts On
hold unless the request sets hold: false, which releases it to the warehouse
at once; a held order needs a later explicit release. The browser New order
releases unless Create on hold is checked. Vault never buys a shipping label: the warehouse buys it
after packing, and its tracking appears on later order reads. Quotes and
selections neither reserve stock nor buy a label or lock a carrier price.
Parcel quoting is the current supported comparison flow. Freight retains its separate workflow. These are application-contract capabilities, not evidence of provider acceptance, a shipment, or a Production release.
Live and Test keys use the same endpoints but cannot be retargeted. A Test key uses ordinary Test business operations when shared Test is configured on the deployment. Stashtab supplies the released origin and organization setup for a customer integration. When Test is unavailable, the request is refused before it can reach Live business data or a provider.
Limited service caller and separate reporter
A registered nonhuman client with an explicit customer binding can use
OAuth client_credentials for the Warehouse HTTP or MCP resource. Stashtab
provisions its client and the narrow operation grant; these are not customer
API keys or person memberships. The HTTP resource is
$VAULT_BASE_URL/v1, and the MCP resource is $VAULT_BASE_URL/mcp. Request
a token for the exact resource; a token for one cannot call the other.
TEST grants retain their existing limited operations. A live inbound binding
is admitted only when its entire allowed-operation list is exactly
listOpeningFeed. Live capture, correction, other reads and reporter access
remain denied. Provisioning a live client does not prove an external consumer
has ingested a report.
Never put the secret in a browser or public document.
curl --user "$SERVICE_CLIENT_ID:$SERVICE_CLIENT_SECRET" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "resource=$VAULT_BASE_URL/v1" \
"$VAULT_BASE_URL/api/auth/mcp/token"
A token expires after five minutes. Every call rechecks the current client,
customer, environment and allowed-operation grant. Revocation takes effect
even on an unexpired token and old outcome reads. The service can use only customer-safe operations named in its current grant
and marked LimitedTestService on their generated reference pages. An
operation outside either list is denied. It cannot count or accept goods,
write openings, administer users or billing, or call another customer. The TEST
reporter is a different registered outbound binding held by Vault. Its
credential cannot act as the inbound service and it sends only the applicable
factual report or notice from a completed Warehouse operation. Real external
credentials, wire fields, accepted readback and notifications remain a separate
go-live verification.
Opening capture and correction do not require that outbound reporter. The openings feed is an ordinary organization-scoped customer read for Viewer or above through a signed-in HTTP session, a verified confidential HTTP integration, or a person-delegated MCP connection with current consent. A separately provisioned nonhuman reader is optional, not an opening-specific prerequisite. The consumer tracks its own ingestion and corrections.
MCP callers
The MCP resource is $VAULT_BASE_URL/mcp. Read its OAuth protected-resource
metadata and the authorization server’s discovery document before starting
the authorization-code flow. The registered client uses PKCE (S256), the
actual resource audience, and the person’s consent. Consent names the selected
organizations; later membership in another organization does not widen it.
GET /api/auth/.well-known/oauth-protected-resource
GET /api/auth/.well-known/oauth-authorization-server
POST /mcp (Bearer access token; JSON-RPC tools/list or tools/call)
MCP tool names and schemas are in the generated tool catalog.
The tool’s organizationId is an input selector, not a permission override.
Revoking consent, removing membership, or unlinking the verified external
subject denies later calls and old receipt reads. A confidential HTTP client
credential does not by itself authenticate an MCP call. An organization API
key is the exception: its Bearer vak1... credential authenticates the same
explicitly marked customer operation over HTTP and MCP.
See the contract-checked examples for tool arguments and denied scope behavior.