Providers, Models, And Provider Keys

Providers and models define where gateway traffic goes.

Provider

A provider represents an upstream service within an organisation.

Fields:

• type: OPENAI, ANTHROPIC, GOOGLE, AZURE_OPENAI, VLLM, or CUSTOM.
• name: human-readable label.
• baseUrl: upstream base URL.
• timeoutMs: optional request timeout override.
• config: provider-specific JSON.
• enabled: whether the provider can be used.
• organisationId: tenant owner.

There is a uniqueness rule for provider type per organisation.

Provider API Key

A provider API key is the upstream secret used by the gateway.

Fields:

• providerId
• name
• key
• keyPreview
• revoked

The UI encrypts the provider key in the browser before persistence. The server decrypts it in memory only when an upstream call needs it.

Provider Key Encryption

Encryption envelope:

{
  "v": 1,
  "alg": "RSA-OAEP-256/A256GCM",
  "keyId": "provider-key-rsa-20260324",
  "wrappedKey": "...",
  "iv": "...",
  "ciphertext": "..."
}

Flow:

1. Browser imports the configured RSA public key.
2. Browser creates a random AES-256-GCM key.
3. Browser encrypts the provider key with AES-GCM.
4. Browser wraps the AES key with RSA-OAEP SHA-256.
5. UI stores the JSON envelope in ProviderApiKey.key.
6. UI stores a masked keyPreview.
7. Gateway loads model/provider-key metadata.
8. Gateway decrypts the envelope with the private key immediately before upstream use.
9. Gateway caches plaintext in memory briefly, keyed by provider-key ID, key ID, and update timestamp.

Legacy plaintext rows are accepted by the gateway during rollout, but new keys should be encrypted.

Model

A model is the organisation-facing catalog entry used by API keys and requests.

Fields:

• name: the model name clients send to Odock.
• slug: the upstream provider model name.
• type: chat, reasoning, image, embeddings, audio, moderation, transcription, or tts.
• capabilities: vision, reasoning, and/or tool_use.
• providerId: provider mapping.
• providerApiKeyId: upstream credential mapping.
• config: model-specific JSON.
• pricing: billing JSON.
• policies: rate-limit/IP policy JSON.
• organisationId: tenant owner.

The model name is unique inside an organisation. The gateway can rewrite the inbound model name to the upstream slug before calling the provider.

Model Access

API keys do not automatically get access to every model.

ApiKeyModelAccess grants:

• one API key,
• one model.

The gateway checks the grant after decoding the request and before applying provider config. If an API key has model access records, the request model must be in the allowed set.

Provider Selection At Runtime

The gateway resolves provider settings like this:

1. Authenticate the Odock API key.
2. Decode the model requested by the client.
3. Check model access for that key.
4. Load the model by organisation and name.
5. Ensure the provider exists and is enabled.
6. Map provider type to runtime provider name.
7. Apply provider base URL and timeout.
8. Resolve provider API key, decrypting if needed.
9. Rewrite the upstream model if slug differs from name.
10. Call the provider or smart router.

Pricing

Model pricing is stored as JSON on the model row and used by the usage billing calculator.

Supported pricing shape:

{
  "input": {
    "text_cost_per_1k_tokens": 0.005,
    "image_cost_per_1k_tokens": 0,
    "audio_cost_per_1k_tokens": 0,
    "video_cost_per_1k_tokens": 0,
    "reasoning_cost_per_1k_tokens": 0
  },
  "output": {
    "text_cost_per_1k_tokens": 0.015,
    "reasoning_cost_per_1k_tokens": 0.015
  },
  "cached_input_discount_percent": 50,
  "tools": {
    "definition_cost_per_1k_tokens": 0,
    "input_cost_per_1k_tokens": 0,
    "output_cost_per_1k_tokens": 0
  },
  "embeddings_cost_per_1k_tokens": 0
}

Costs are computed in integer nanos USD to avoid floating-point drift.

Setup Checklist

1. Create the provider.
2. Create at least one provider API key.
3. Create a model with a user-facing name and upstream slug.
4. Assign the provider and provider key to the model.
5. Add pricing if budgets, invoices, or cost tracking matter.
6. Add policies if this model needs custom rate limits.
7. Grant API key model access.
8. Test with the playground or a direct gateway request.