On this page
01
What you'll set up
Your apps should not hold provider secrets. In about ten minutes you will store your provider keys in Cloptima once, check that they work, and let the gateway use them for every request. Your apps only ever see virtual keys.
- One credential per provider account you want to use
- A test that proves each credential works
- Credentials attached where you want them used
- A rotation and revocation routine
You need an owner or admin role and a key from each provider you plan to use.
02
Cloud key or edge key
Each credential has a storage mode. It decides where the secret lives.
Cloud API Key
- Stored securely in Cloptima
- Used by the cloud gateway for your requests
- The quickest way to start
Edge BYOK (stay in your VPC)
- The key lives only on your own edge gateway
- Cloptima enforces policy and tracks usage without ever seeing the key
- For workloads that must keep provider keys inside your network
The guide on running the edge gateway covers the second option in full. The rest of this guide uses cloud keys.
03
Add a credential
Credentials are on the Provider Credentials card in AI → Credentials & Keys.
- 1
Choose + Add Credential
It is on the Provider Credentials card.
- 2
Pick the Provider
Choose from the list, or Custom for any OpenAI-compatible endpoint.
- 3
Pick the Storage Mode
Choose Cloud API Key.
- 4
Enter a Display Name
Use a name that says whose account it is, such as OpenAI prod key.
- 5
Enter the provider's fields
See the table below.
- 6
Save
The credential appears in the list as active.
- 2Provider
- OpenAI
- 3Storage Mode
- Cloud API Key
Your API key is stored securely in Cloptima and used when routing requests through the cloud gateway.
- 4Display Name *
- OpenAI prod key
- 5API Key *
- ••••••••••••••••
- 5Custom API Base (optional)
- https://api.openai.com/v1
04
What each provider needs
Most providers need only an API key. A few need more.
| Provider | What to enter |
|---|---|
| OpenAI, Anthropic, Google / Gemini, Cohere, Mistral, Groq, Together AI, OpenRouter, xAI, Fireworks, DeepSeek, Perplexity, Moonshot, and similar | API key |
| Azure OpenAI | API key, API base URL, and API version |
| AWS Bedrock | Region, access key ID, and secret access key |
| Google service account / Vertex AI | Service account key, project ID, and location |
| Custom (OpenAI-compatible) | API key and API base URL |
05
Test a credential
Test proves a credential works before real traffic depends on it.
- 1
Choose Test on the credential
Cloptima makes a small call with it.
- 2
Read the result
A pass shows the time it was validated. A failure shows the reason.
- 3
Use Test All for a full check
It tests every active credential.
06
Use the credential
Add a credential and nothing changes until you point traffic at it. There are three places to do that.
| Where | Effect |
|---|---|
| Policy: Default upstream credential | Every request on the policy uses it |
| Policy: Per-provider credential overrides | A different credential for each provider |
| Virtual key: credential override | One key uses a specific credential |
When you ask for a model by name, Cloptima chooses among the providers you have credentials for.
07
Send a key for one call only
Sometimes a key should never be stored. You can send it with a single request instead.
curl https://api.cloptima.ai/v1/ai/chat/completions \
-H "Authorization: Bearer $CLOPTIMA_VIRTUAL_KEY" \
-H "x-cloptima-provider-api-key: $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Say hello"}]}'The key is used for that call, not stored, and policy, budgets, and guardrails still apply. To use a stored credential for one call, send its id in x-cloptima-provider-credential-id.
08
Rotate a credential
Providers ask you to rotate keys, and so should you.
- 1
Create a replacement key at the provider
Keep the old one active for the moment.
- 2
Choose Rotate on the credential
Enter the replacement key. For Bedrock, enter both the access key ID and the secret.
- 3
Test
Confirm the credential passes.
- 4
Delete the old key at the provider
Do this last.
Apps and virtual keys keep working through a rotation, because they refer to the credential, not to the secret.
09
Revoke a credential
Revoke ends a credential's use at once.
| After you revoke | What happens |
|---|---|
| Requests bound to it | They are refused with a message that names the credential problem |
| Model selection | The provider is taken out of the choice, and the response says why |
| The credential list | It moves to the Revoked filter, and stays there for your records |
10
Filter and review
The list has filters for Active, Invalid, Revoked, and All. Each row shows the provider, the storage mode, the last test result, and when it was created.
- Review the list each quarter
- Revoke credentials nobody uses
- Retest anything that has not been tested lately
11
If something goes wrong
Most problems are in the key or in the extra fields.
| What you see | Likely cause | Fix |
|---|---|---|
| Test fails with an authentication error | The key is wrong, expired, or lacks access | Create a new key at the provider and rotate |
| Test fails for Azure OpenAI | The API base URL or version does not match the deployment | Check both fields in the Azure portal |
| Bedrock test fails | Region or permissions are wrong | Check the region and that the key may invoke the model |
| Requests ignore the credential | It is not attached to a policy or a key | Set it as Default upstream credential or an override |
| A provider is never chosen for a model name | There is no usable credential for it | Add a credential, or check that it is not revoked |