BYOK guide

A comprehensive reference for tenant administrators managing AI provider credentials in the Monago Governance Gateway.

1. Overview

Monago applies a BYOK (Bring Your Own Key) model — the customer brings their own AI provider API key (OpenAI, Anthropic, AWS Bedrock). Monago operates as a governance gateway:

• Enforces governance rules at the tenant, workspace, and user levels.
• Captures an integrity-protected audit trail for every request.
• Provides observability, cost analytics, and compliance posture.

Token usage is billed directly by the AI provider to the customer; Monago uses a separate subscription model for the governance and audit layer.

2. Prerequisites

• A Monago account with the admin role.
• Access to the AI Providers menu.
• Plaintext API key from your AI provider (see section 3).
• A password manager or internal secret vault to store the plaintext after the show-once dialog.

3. Acquiring the API key from the provider

3.1 OpenAI

3.2 Anthropic

3.3 AWS Bedrock

4. Configuration in Monago

4.1 Open AI Providers

4.2 Add the credential

Monago validates the key against the provider's metadata endpoint with a short timeout. The "Validating key…" indicator is displayed during the operation.

4.3 Show-once dialog (important)

After successful validation, the show-once dialog opens.

5. Managing credentials

5.1 Credential list

The AI Providers tab shows the credentials table with columns: name, provider, masked key display, status, created date, and actions. Filter chips above the table support filtering by provider and status.

5.2 Disable temporarily

To pause use of a credential without permanent revocation.

When the credential is disabled, the gateway:

• Cloud: uses the platform's default key if the deployment administrator has configured one.
• On-premise: returns a configuration error since there is no fallback.

Re-enable: row action → Enable.

5.3 Rotate the key

Scenarios that require rotation:

• Your organisation's compliance policy (periodic rotation).
• A suspected key compromise.
• The provider has revoked the key from their side.

The old key is replaced by the new one; the gateway begins using the new key on the next request.

5.4 Revoke a credential

A permanent action — the credential is revoked while the audit trail is retained.

The status changes to Revoked. A revoked credential cannot be re-enabled — create a new credential if needed.

6. Troubleshooting

"Invalid API key"

Common causes:

• Whitespace introduced during copy-paste (leading or trailing spaces or newlines).
• The key has expired or been revoked at the provider.
• The provider account billing status is inactive.
• The key scope does not include the metadata endpoint.
• An incorrect base URL when using a custom endpoint.

The provider's response message is surfaced on the "Provider detail:" line below the main error to support diagnosis.

"Credential name already used for this provider"

Each tenant + provider combination requires a unique name. Use a version suffix, e.g. production-openai-v2.

"AI provider credential not found"

• The credential may have been revoked by another administrator in your tenant.
• Refresh the page to load the latest state.

Gateway request fails after the credential is disabled

This is expected behaviour. When the credential is disabled, the gateway will use the platform's default key if the deployment administrator has configured one. If no fallback has been configured (typical on-premise), the gateway returns a configuration error. Resolution: re-enable the credential through the UI.

Show-once dialog does not appear after submit

Common causes:

• Metadata-only operations (without key rotation) do not produce a new plaintext. The table will show the credential with a masked display.
• A network error — check the browser DevTools console.

Validation timeout

The provider's metadata endpoint occasionally exhibits higher latency. Retry the request; transient errors are common. If the issue persists, contact provider support.

7. FAQ

7.1 How is my API key encrypted?

Monago applies at-rest encryption using industry-standard cryptographic controls. Plaintext is decrypted only for the duration of an inference request handled by the gateway.

For production deployments, Monago supports envelope encryption with Customer-Controlled Key Management Service (KMS). The Monago team has no operational authority over the customer's KMS, so plaintext recovery requires customer authorisation.

7.2 Can the Monago team see the plaintext of my API key?

No. The plaintext is encrypted at rest and decrypted only for the duration of an inference request. No product workflow re-presents the plaintext after the show-once dialog closes.

7.3 Does the audit log record the plaintext API key?

No. The audit log records credential metadata: provider, credential name, the last four characters of the key, and field-level changes. The prohibition on writing plaintext to the audit log is enforced by an automated regression test that runs on every release.

7.4 The plaintext was lost after the show-once dialog. How do I recover access?

Plaintext recovery through Monago is not available; rotate the credential.

7.5 Can multiple administrators manage credentials?

Yes. Every user with the admin role on the tenant can view, create, rotate, disable, and revoke credentials. The audit log records the user performing each action.

7.6 Is there a limit on the number of credentials per tenant?

There is no hard limit during the pilot. Recommendation: 1 to 3 credentials per provider (e.g. prod, staging, dev). When multiple active credentials exist for one provider, the gateway uses the most recently created credential.

7.7 Can on-premise deployments use BYOK?

Yes. The UI flow is identical. Differences:

• The super_admin role is not available on-premise — admin is the highest authority.
• The fallback default key is optional and configured by the deployment administrator.
• KMS encryption is customer-managed.

7.8 What happens if my tenant is deleted?

Deleting a tenant also releases and removes all associated credentials. The audit log is retained for forensic needs. Confirm with support before performing destructive operations.

8. Security best practices

9. Compliance mapping

Per-clause mapping detail and the evidence package are delivered in a separate procurement document — contact support@monago.io for a PDF copy.

10. Support