> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adaptyvbio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrator & Partner Guide
> How to integrate the Foundry API into your platform with a BYOK flow, and when to apply to the Partner Program.
# Integrator & Partner Guide
The [Foundry API](/api-reference/api-introduction) aims to make wetlab data requests as simple as a (somewhat slow) Modal call or DB query.
We want all of our users to have access to this capability and their results data in all of their tools, and to make it easy for developers to build rich applications on top of our API, or enrich their existing apps with our lab capabilities.
## How to integrate: BYOK flows only
The beauty of APIs vs. integrations is that they allow flexibility, for the providers, developers, and the users.
To maintain this flexibility, and because wetlab work requires a tight feedback loop (see [Service providers and reselling](#service-providers-and-reselling) below), we require you to implement a **B**ring **Y**our **O**wn **K**ey (`BYOK`) flow. This is a common pattern for AI model providers, where users choose which account(s) they want to link to your platform by pasting their scoped API keys. This means you must not "bundle" user orders under your own key — instead, the user should provide the token they received from the [Foundry portal](https://foundry.adaptyvbio.com/) (or, if you are a [partner](https://www.adaptyvbio.com/api/apply) who has onboarded them, the token you have minted for them).
Since the keys allow all the actions of their owner (modulo attenuation), for security purposes you must never store them as plain text. In descending order of priority and security, we recommend:
1. Don't store them at all — prompt the user for the key each session.
2. Store them encrypted client-side.
3. If you must persist them, store them encrypted server-side.
If you hold the keys for the users on your servers, we encourage you to attenuate tokens down to the minimal required permissions for the actions your integration performs.
You can send users to the Foundry token creation screen directly via [`https://foundry.adaptyvbio.com/request-token`](https://foundry.adaptyvbio.com/request-token) to streamline adding the token. To streamline even further, you can apply to our [Partner Program](https://www.adaptyvbio.com/api/apply).
## Partner tokens
If you are accepted into our [Partner Program](https://www.adaptyvbio.com/api/apply), you gain the ability to create keys with the partner role. These keys allow you to call the partner-only routes — currently just one:
* `POST /api/v1/partners/mint-token` — mint a user token for a customer.
* With `org.type: "new_org"`: bootstrap a new organization (when the customer's email domain has no org on our platform yet) and create its first user.
* With `org.type: "existing_org"`: add a new user and mint their token inside an org you previously onboarded.
* Users must be new — an existing email is rejected with `409`. Tokens default to a 90-day expiry; pass `expires_at` to override.
Partner tokens should be kept safe and stored separately from your own API keys used for data access.
The `mint-token` action lets you create tokens for users that do not yet have any organization (as determined by their email domain) on our platform. You can also add users to organizations you have onboarded, or mint additional tokens for users that belong to those organizations.
For customers you have not onboarded, you can request a token via [`https://foundry.adaptyvbio.com/request-token`](https://foundry.adaptyvbio.com/request-token), which triggers a pre-filled version of our [standard token creation flow](/api-reference/api-introduction#getting-an-api-token). The user can then copy and paste the token into your platform as in any non-partner BYOK flow (see above).
Per the partner agreement, you may not use any of these tokens except on behalf of the user (for example, placing orders or accessing their data outside of providing them services). If you need service tokens for agents, you should attenuate existing user tokens appropriately.
For details on the partner-only API calls, fetch the OpenAPI spec while authenticating with your partner token:
```bash theme={null}
curl -H "Authorization: Bearer $PARTNER_TOKEN" \
https://devs.adaptyvbio.com/api/v1/openapi.json
```
The returned JSON will describe the partner-exclusive routes in more detail.
## Service providers and reselling
We distinguish service providers and resellers based on who the end consumer of the data from our API is — both in terms of billing and in terms of who actually consumes the data.
If you are running a campaign on behalf of a customer, and they never (want to) see the raw data but are only interested in the final IP, then you probably qualify as a **service provider**, especially if you have discretion over the budget of the campaign.
If the customer retains day-to-day control over the budget (instead of, e.g., delegating you a lump sum) and/or wants to review the raw data themselves, then *they* are the actual data consumer and we would classify you as a **reseller** or **distributor**.
For reselling and distribution, you must apply to the [Partner Program](https://www.adaptyvbio.com/api/apply) and either manage your customers' tokens for them or request that they give you access via their existing tokens.
We need a direct relationship with the data consumer because, during an experiment, a lot can change. Due to the nature of biology, ordered sequences might not express, initial data might show that running more replicates to get exact $K_d$ estimates is pointless, or additional runs might be required. We need to be able to communicate directly with the data users to sort these things out and to adjust the order and invoicing accordingly.
Even if you are a service provider under this definition, we strongly encourage applying to the [Partner Program](https://www.adaptyvbio.com/api/apply) and provisioning keys for your customers. It makes it much easier for us to respond to any follow-up questions the customers might have, and it makes it easier for you to manage the blast radius of any integration you build.
### Which bucket are you in?
```mermaid theme={null}
flowchart TD
Start([You want to integrate with the
Adaptyv API on behalf of customers]) --> Q1{Does the customer ever
want to see the raw data?}
Q1 -->|Yes — they review
the raw data themselves| Reseller
Q1 -->|No — they only care
about the final IP| Q2{Do you have discretion
over the campaign budget?}
Q2 -->|No — customer retains
day-to-day budget control| Reseller
Q2 -->|Yes — customer
delegates a lump sum| ServiceProvider
Reseller[Reseller / Distributor]:::rs
ServiceProvider[Service Provider]:::sp
Reseller --> RSNext["Partner Program required.
Manage customer tokens for them,
or request access via their tokens.
Adaptyv needs a direct relationship
with the data consumer to handle
mid-experiment changes and invoicing."]:::rsAction
ServiceProvider --> SPNext["Standard BYOK flow is sufficient.
Users paste their scoped API keys
via foundry.adaptyvbio.com/request-token.
Strongly encouraged: apply to the
Partner Program to provision keys for
customers — easier follow-ups and
smaller blast radius."]:::spAction
classDef sp fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#155724
classDef rs fill:#fff3cd,stroke:#ffc107,stroke-width:2px,color:#856404
classDef spAction fill:#f8f9fa,stroke:#28a745,stroke-width:1px,color:#212529
classDef rsAction fill:#f8f9fa,stroke:#ffc107,stroke-width:1px,color:#212529
```
## Next steps
REST endpoints, authentication, and the experiment lifecycle.
Drive the same endpoints from Claude, Cursor, or any MCP-aware client.
Mint tokens for your customers and unlock partner-only routes.
Create and manage API tokens, organizations, and users.