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. Choose an exact live Singular model ID for that provider; do not use auto for this check.
2. Send a small Chat Completions request with your Singular API key.
3. Confirm the Singular response succeeds, then check the upstream provider's usage or audit view for the new request.
4. If no upstream activity appears, treat BYOK selection as unverified. The current UI enable toggle is not an independently enforced backend routing control, and a matching stored credential is only one input to gateway credential selection.

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

Credential deletion is not a verified backend contract in this release. Do not rely on the UI detach control as the final revocation step. Revoke the credential at the upstream provider, confirm it can no longer authenticate there, and remove or replace the masked attachment in Settings.

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.