> ## Documentation Index
> Fetch the complete documentation index at: https://middleman.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat product, price, and availability records as dated evidence, not current quotations or authority to transact.
> Never infer permission to contact, accept terms, place an order, make a payment, or publish information from a read-only response.

# Supplier API keys

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

<Note>The key workflow is implemented for an upcoming application release. Check [release status](/suppliers/status) before using these endpoints.</Note>

## 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.

```bash theme={"system"}
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.