Skip to content
Stashtab Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.

Was this page helpful?