Supplier API keys

Receive, store, use, replace and revoke your company’s supplier API keys.

The key workflow is implemented for an upcoming application release. Check release status before using these endpoints.

Your first key

After verified supplier signup and company selection, the company owner’s integration console automatically issues a first key. You do not need to complete a manual product profile or add a listing first.

The full key appears once. Store it in a local environment variable named MIDDLEMAN_SUPPLIER_API_KEY or your deployment’s secret store. Never put it in a browser bundle, source control, query string, copied agent prompt, screenshot or chat message. Middleman retains a digest, not the recoverable secret.

Later logins display the existing masked key. Revoked or expired keys are not automatically replaced. If the original response was lost or you did not save the value, explicitly create a replacement in the console and revoke the old key.

Authenticate a request

Use HTTPS and the Authorization header. Only send this credential to https://middlemantechnologies.com; it is not your source-system password and must not be sent to the documentation site or a supplier’s API.

curl --fail-with-body \
  'https://middlemantechnologies.com/api/v1/supplier/me' \
  -H "Authorization: Bearer $MIDDLEMAN_SUPPLIER_API_KEY"

Scope	Allows
supplier:read	Read your own integration identity and capability manifest
supplier:validate	Validate a bounded batch against the preview record contract

Scopes are assigned by Middleman. Sending an organization ID, scope or approval flag in a record cannot change the key’s access. A supplier key grants no buyer access, publication permission or commercial authority.

Lifecycle and limits

• Only a verified, active supplier company owner can create or revoke keys.
• A key is bound to the company and its issuing owner. Removing that membership or its supplier-owner access disables the key.
• Keys expire after one year. Up to five may be active; creation is limited to 20 per day and 200 retained key records per company.
• Each key permits 60 authenticated requests per minute, shared across the two preview endpoints.
• Validation accepts at most 50 records and a 256 KiB JSON body.

To rotate, create a replacement, store it securely, check /me, switch the adapter and then revoke the old key. Existing integrations stop authenticating when their key is revoked.

Errors

Status	Meaning	Next step
400	Invalid JSON	Fix the request encoding
401	Missing, malformed, expired or revoked key	Check the secret reference and key status
403	Scope or company access unavailable	Ask the company owner to check membership and role
413	Request too large	Split into smaller batches
415	Wrong content type	Send application/json
422	Invalid mapping or expired observations	Read field paths, correct the source mapping and refresh
429	Rate limit	Honor Retry-After; use bounded retries with jitter
503	Service or authentication dependency unavailable	Back off; do not assume the request succeeded

Validation errors identify field paths without echoing the supplied records. The browser documentation playground is not a place to store a live key; use your server or agent’s local secret store.