Bring your own provider key

Before you attach a key

Create a dedicated upstream-provider key with the narrowest permissions and spend limit that your workload needs. Keep your Singular API key available too: BYOK changes the upstream credential, but it does not replace Singular authentication, policy, metering, or balance checks.

1. Attach the provider credential

1. Open Settings → BYOK while signed in.
2. Choose the matching provider and paste the newly created upstream key.
3. Save the credential once. Do not paste it into a thread, browser console, support ticket, or client-side environment variable.
4. Reload the page and confirm that the provider shows masked attached state. The full secret must not be returned.

The browser sends a new credential to the server once. The gateway stores the secret; later reads expose only masked metadata, and decryption occurs only inside the gateway request path.

2. Verify a matching request

1. Turn on Use my key when available in Settings. That switch drives gateway routing policy: with it on, a request to a provider you have attached a credential for is sent with your key; with it off, the request routes on platform credentials even though the credential stays attached.
2. Choose an exact live Singular model ID for that provider; do not use auto for this check.
3. Send a small Chat Completions request with your Singular API key.
4. Confirm the Singular response succeeds, then check the upstream provider's usage or audit view for the new request.

If no upstream activity appears, re-check the switch and confirm that the attached provider actually serves the model you pinned. A credential attached for one provider does not affect models served by another.

3. Replace and rotate safely

1. Create the replacement key upstream before revoking the old key.
2. Replace the saved credential in Settings and repeat the exact-model verification request.
3. Confirm activity on the new key, then revoke the old key at the upstream provider.
4. Test the expected failure or fallback behavior for an expired, rate-limited, or model-restricted credential.

Recover or remove access

Detaching in Settings removes the credential: the stored secret is deleted and later requests route on platform credentials. Treat that as one half of the job. Also revoke the key at the upstream provider and confirm it can no longer authenticate there, because a secret that leaked before you detached it stays usable until the provider revokes it.

Billing boundary

Settings-created Singular API keys remain on credit billing, so attaching a provider key does not bypass low-balance rejection and can result in both upstream-provider charges and Singular retail credit consumption. Apply spend limits and alerts in both systems.