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

> ## Agent Instructions
> The PartFinder API is served at https://api.partfinder.dev. Authenticate with `Authorization: Bearer $PARTFINDER_API_KEY`; create an account at https://console.partfinder.dev/sign-up and pick pay as you go or a monthly or yearly plan (see https://partfinder.dev/pricing), then create a key. Pay as you go starts with 100 free credits, once per person and per company.
> Install the PartFinder agent skill with `npx skills add https://docs.partfinder.dev` (skill file: https://docs.partfinder.dev/skill.md).
> The OpenAPI document at https://api.partfinder.dev/v1/openapi.json is the source of truth for request and response schemas.
> What each call costs and current plans: https://api.partfinder.dev/llms.txt.

# PartFinder API Authentication: Create and Use API Keys

> PartFinder uses organization-scoped API keys sent as Bearer tokens. Create and manage keys at console.partfinder.dev.

PartFinder authenticates every request with an API key passed as a Bearer token in the `Authorization` header. Keys belong to your organization, not to a team member, and keep working when someone joins or leaves your team.

## Creating an API key

**1. Open the API Keys settings**

Sign in at [console.partfinder.dev](https://console.partfinder.dev) and open **Settings → API Keys**. Anyone can create an account at [console.partfinder.dev/sign-up](https://console.partfinder.dev/sign-up). Keys belong to your organization.

**2. Create a new key**

Click **Create API key** and give it a descriptive name that identifies its purpose and environment (for example, `production-erp-integration`). A name cannot be changed later; the description and expiration can.

**3. Copy the key immediately**

Copy the key as soon as it appears. The console shows it only once and cannot retrieve it afterward. Store it somewhere secure before closing the dialog.

> [!TIP]
>
> Name each key after the system that uses it, for example `production-erp-integration` or `staging-bom-service`.

## Sending the key

Include your API key in the `Authorization` header of every request using the `Bearer` scheme:

```http theme={null}
Authorization: Bearer <your-key>
```

The `/v1/ping` endpoint is the fastest way to confirm your key is wired correctly before calling anything that costs credits.

```python Python theme={null}
import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)

data = response.json()
print(data["authenticated"]["organization_id"])
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.partfinder.dev/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});

const data = await response.json();
console.log(data.authenticated.organization_id);
```

```bash cURL theme={null}
curl https://api.partfinder.dev/v1/ping \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"
```

A successful response confirms the key is valid and returns the organization it belongs to:

```json theme={null}
{
  "as_of": "2026-09-19T14:23:00Z",
  "summary": "Authenticated. The PartFinder API is reachable and this key is valid.",
  "notice": "Informational only. Risk scores, stock levels, lead times and alternate-part suggestions may be incomplete, delayed or inaccurate. Independently verify before making procurement, engineering, compliance, safety or sourcing decisions.",
  "authenticated": {
    "organization_id": "org_2b7c...",
    "key_id": "ak_9f31..."
  }
}
```

## Serving your own customers

If you offer PartFinder inside your own product, give **each of your customers its own key**, created
by your code with [`POST /v1/keys`](https://docs.partfinder.dev/api-reference/keys/create-a-key-for-a-customer) and one of your
organization's own keys:

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.partfinder.dev/v1/keys",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
    json={"company": "Acme Corp"},
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.partfinder.dev/v1/keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ company: "Acme Corp" }),
});
console.log(await response.json());
```

```bash cURL theme={null}
curl -X POST https://api.partfinder.dev/v1/keys \
  -H "Authorization: Bearer $PARTFINDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company": "Acme Corp"}'
```

The response carries the new key's `secret` once, and an `end_customer_id` naming that customer.

* **Each customer sees only its own data.** Requests for quote, BOMs, searches and comparisons made with a customer's key
  belong to that customer: its keys list and read only those, and another customer's id answers `404`.
  Your organization's own keys see everything.
* **Requests for quote name the customer.** When a request for quote sent with a customer's key names
  no requester company, the customer's company is used.
* **Replies are told to the customer.** A request for quote sent with a customer's key needs
  `notify_email`: that address alone is emailed when the supplier replies, never your organization's
  people. Without it the request answers `400` and nothing is sent.
* **Several keys, one customer.** Send `end_customer_id` instead of `company` to add a key to a customer
  you already created. To replace a leaked key, create the new one, move the customer over, then revoke
  the old one with [`DELETE /v1/keys/{id}`](https://docs.partfinder.dev/api-reference/keys/revoke-a-customer-key). The customer's
  data stays.
* **Rate limits.** Each customer can make as many calls as your organization, and your organization's
  limit applies to all of them together. See [Rate limits](https://docs.partfinder.dev/errors.md#rate-limits).
* Customer keys cannot create, list or revoke keys (`403 key_not_allowed`).

[`GET /v1/keys`](https://docs.partfinder.dev/api-reference/keys/list-customer-keys) lists your customers' keys, never their secrets.
The `key_id` in every response tells you which key served the call.

## Revoking keys

Revoke a key at any time from **Settings → API Keys** in the console: click the key's **Revoke** button, type `Revoke` to confirm, and click **Revoke key**.

Every member of your organization sees its keys and can create one. Members can edit, rotate and revoke the keys they created; admins can change any key. See [Console](https://docs.partfinder.dev/console.md) for roles and inviting teammates.

## Rotating keys

The **Rotate** button on a key creates a replacement (same name, with a rotation stamp), shows its secret once, and revokes the current key. Update your integration with the new secret within a minute: the previous secret keeps working that long, so there is no gap. A key you created for one of your customers keeps belonging to that customer after it is rotated.

> [!NOTE]
>
> Revocation takes effect within about a minute; until then the key may still be accepted. Unknown, revoked and expired keys all return `401` `invalid_key`.

## Key security

Follow these practices to keep your API keys secure:

* **Use environment variables.** Store keys in environment variables or a secrets manager. Never hardcode a key in source code or commit one to version control.
* **Rotate keys regularly.** Rotate keys on a schedule, and immediately when a team member with key access departs.
* **Use one key per environment.** Create separate keys for development, staging, and production so you can rotate or revoke one without affecting the others.
* **Limit key distribution.** Only the systems that need to call the API should have access to the key. Avoid sharing keys between unrelated services.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.