Your own provider keys

You can bring your own key for a provider. Requests to that provider then go through your account with it: you pay the provider directly, and ai.ml charges only a platform fee.

Open Own keys in the sidebar. The screen is titled Your own provider keys and shows one card per provider that accepts a customer key.

Adding, replacing, validating and deleting keys needs the owner or admin role. Other roles can read the screen.

Add a key

1. On the provider's card, press Add key.
2. Paste the key into the API key field.
3. Optionally enter a Label, for example the account the key belongs to.
4. Optionally tick Fall back to our pool if the provider rejects this key. See below.
5. Press Validate and store.

The key is checked against the provider's model list before it is stored. Nothing else is sent during the check. If the provider rejects the key, the form shows the provider's own message and nothing is stored.

Once stored, the key is encrypted and is only ever decrypted to call that provider. Every decryption is written to the audit log. The key itself is never shown again. The card shows a short hint, the last four characters, so you can tell which key is on file.

What a card shows

• The provider's name, the key's label and its hint.
• A status: not set, key required, active or failing.
• Added, Last used and Last validated.
• Platform fee: your fee as a percentage of list price.

A provider with no key reads "no key on file" and its requests use the ai.ml pool at list price. key required marks a provider that can only be reached with your own key.

How requests are routed and billed

While you have a key for a provider, your requests to that provider use your key and no other.

• Through your key. You pay the provider for the usage. ai.ml charges the platform fee: a percentage of what the request would have cost at list price. The introduction on the screen states your percentage with an example. The default is 5 %.
• Through the ai.ml pool. The request is billed at list price, like any request without your own key.

The Spend split, last 30 days table at the bottom shows the number of requests and the amount charged on each route: Your own keys (platform fee) and Our pool (list price). It appears once you have usage to show.

See usage and billing.

Fall back to the pool

The checkbox Fall back to our pool when the provider rejects this key decides what happens when the provider refuses your key.

• On. The request is served through the ai.ml pool and billed at list price.
• Off. The request fails. With fallback off, a request for that key is also not moved to any other provider.

You can change it at any time from the card. The change is saved as soon as you tick or clear the box.

When a key is failing

When the provider rejects your key, the card turns to failing and says since when, with the provider's error. ai.ml also sends a byok.failing webhook; see webhooks.

What happens to requests depends on the fallback setting: they fall back to the pool at list price, or they fail until you replace the key.

To fix it, replace the key, or correct the problem at the provider and press Validate.

Validate a key

Validate checks the stored key against the provider again. The card then says that the provider accepted the key and how many models it can see, or shows the provider's message.

Replace a key

Press Replace key and store the new key the same way. The key you have now keeps serving until the new one is stored, then it is retired. A provider holds one active key at a time.

Retired keys are listed under Replaced keys with their hint and the time they were retired.

Delete a key

1. Press Delete on the card.
2. Type the provider's id, as shown in the confirmation, and press Delete key.

Requests to that provider go back to the ai.ml pool at list price.

Related

• BYOK API reference
• Reselling ai.ml: a reseller's markup does not apply to requests made through a customer's own provider key.