BYOK is the credential model used for every integration in NimbusOS. You bring your own API key or OAuth credential for every third-party service, the platform encrypts it at rest, and usage charges go directly to your provider account. This article covers the credential storage model, the rotation workflow, the audit trail, and the operational patterns for managing dozens of credentials across an agency workspace.
What BYOK Means in NimbusOS
Three principles.
Your credential, your account. When you call Apollo through NimbusOS, the call uses your Apollo API key. Apollo charges your Apollo account. NimbusOS does not proxy billing or take a cut.
Workspace-scoped. Each workspace has its own set of credentials. An agency with ten sub clients can configure per-sub-client credentials, so each sub client pays their own provider bills.
Encrypted at rest. Credentials are stored with Fernet symmetric encryption. The encryption key is workspace-scoped and rotated on a schedule.
The Credential Model
Two models cover every integration.
EnrichmentProviderKey. For providers that use static API keys (Apollo, Clearbit, ZoomInfo, Hunter, ZeroBounce, etc.). Fields: provider name, workspace reference, encrypted API key, active status, created_at, last_used_at.
OAuth token storage. For providers that use OAuth (HubSpot, Gmail, Microsoft 365, etc.). Fields: provider name, workspace reference, encrypted refresh token, encrypted access token, expires_at, active status.
Both models share the same encryption and audit pattern.
Fernet Encryption
Fernet is a symmetric authenticated encryption scheme built on AES-128-CBC for encryption and HMAC-SHA256 for integrity. The implementation is Python's cryptography.fernet.Fernet.
What this means in practice.
The ciphertext includes a version identifier, a timestamp, and an HMAC. Tampering with the ciphertext produces a decryption failure, not a quietly wrong plaintext.
The encryption key is 256 bits (URL-safe base64-encoded 32 bytes). Keys are stored outside the database, in the application secrets store.
Decryption requires both the ciphertext (in the database) and the key (in the secrets store). A database backup alone is insufficient to decrypt.
Per-Workspace Key Isolation
Each workspace gets its own Fernet key. This is critical for multi-tenant isolation.
When workspace A's credentials are decrypted, the decryption uses workspace A's key. Workspace B's credentials, even in the same database table, cannot be decrypted with workspace A's key.
If workspace A's key is ever compromised, only workspace A's credentials are at risk. Other workspaces continue to operate with their own keys unchanged.
Key Rotation
Fernet keys rotate on a schedule. Default rotation is every 90 days. Rotation is transparent to the user.
The rotation process:
- A new key is generated and stored alongside the old key.
- All credentials encrypted with the old key are decrypted and re-encrypted with the new key.
- The old key is retained for a grace period (30 days) to support rollback.
- After the grace period, the old key is deleted.
During rotation, the integration continues to work uninterrupted. Reads try the new key first, fall back to the old.
Manual rotation can be triggered in Account Settings if you suspect key compromise.
Credential Rotation (Provider Side)
Rotating the provider's API key (because you rotated it in the provider's dashboard, or because the key expired) is a simple flow.
- Open Integrations, find the provider.
- Click Update Credentials.
- Paste the new key.
- Click Test. The platform calls the provider to verify.
- Save.
Behind the scenes, the new key is encrypted and stored. The old ciphertext is overwritten. The AuditLog records the rotation with a reference to the previous key's identifier (not plaintext).
New operations use the new key. In-flight operations complete with the old key.
Audit Logging
Every credential access writes an AuditLog row. Fields:
- User or system process that initiated the access
- Workspace
- Credential identifier (provider name)
- Purpose (campaign send, enrichment job, webhook verification, etc.)
- Timestamp
- IP address (if initiated by user action)
Audit logs are queryable in Account Settings -> Audit. Retention is 12 months by default, longer for enterprise.
Credential access logs do not contain the plaintext credential. They are safe to share with auditors without leaking secrets.
Credential Revocation
Revoking a credential means deleting it from NimbusOS. Three ways to revoke.
Through the integration UI. Open Integrations, click Disconnect with credential removal. Confirm. The ciphertext is hard-deleted; the audit log entry remains.
Through the provider side. Revoke the API key in the provider's dashboard. The next NimbusOS call fails. The integration is marked failed. Credentials remain encrypted in the database until you remove them through NimbusOS or wait for the automatic cleanup.
Automatic cleanup. Credentials for integrations that have been disconnected for 90 days are hard-deleted automatically.
Per Sub-Client Credentials (Agency)
In agency mode, credentials can be scoped per sub client in addition to per workspace. A common pattern:
- Agency-level credential for Apollo (shared across all sub clients for convenience)
- Per sub-client credential for HubSpot (each sub client has their own HubSpot org)
The credential precedence is: sub-client credential if set, otherwise workspace credential. The integration configuration specifies whether to use sub-client or workspace keys for each call.
Credential Testing
The platform tests every credential before saving. The test is a read-only call to the provider (list operation, account info, or similar). A successful test confirms the credential works. A failed test surfaces the provider's error message.
Testing does not consume provider credits because read-only operations are free on most providers.
Credential Health Monitoring
Active credentials are monitored continuously. A credential that has not been used in 30 days fires an informational alert (is it still needed?). A credential that fails authentication three times in a row fires a critical alert and the integration moves to failed status.
Health status is visible in the Integrations health dashboard.
Shared Credentials: When and When Not
Shared credentials (one key used across many workspaces) should never be necessary if BYOK is used correctly. Two edge cases where shared credentials appear:
Managed integrations. NimbusOS offers a managed option for ReachInbox where you pay NimbusOS and NimbusOS manages the ReachInbox account. In this case, NimbusOS uses its own credential, not yours. This is clearly labeled in the integration setup.
Platform-level AI. Claude API calls for reply classification and hyper personalization use a platform-level Anthropic key pooled across workspaces. This is both a cost optimization (NimbusOS has volume pricing) and a capacity optimization (the platform can route around rate limits). Customers with their own Anthropic contract can optionally BYOK for this too.
Encryption Key Backup and Disaster Recovery
Encryption keys are backed up in the application secrets store with the same high availability guarantees as the database.
In a disaster recovery scenario:
- Database backup: restored with standard DB recovery.
- Secrets store: restored from backup, which contains the encryption keys.
- Ciphertexts in the restored database are readable with the restored keys.
Without both the database and the secrets store, the credentials are unrecoverable. This is intentional: a backup leak of only the database does not leak credentials.
Compliance
BYOK supports several compliance requirements.
SOC 2 Type II. Credential handling is audited as part of the platform's SOC 2 audit. Logs, encryption, and rotation are in scope.
GDPR. Credentials containing PII (some provider credentials include email-identified account references) are subject to GDPR deletion requests.
HIPAA and PCI. Not currently certified. Credentials for regulated workflows should not be stored in NimbusOS without a specific enterprise arrangement.
Troubleshooting
"I pasted my key and test failed immediately"
Three likely causes. The key is wrong (typo). The key does not have the required scope (some providers issue keys scoped to specific operations). The provider account is suspended or out of credits.
Check the error message in the test result. It usually identifies which of the three.
"Key test passes but real operations fail"
Possible scope mismatch. The test may use a read-only scope; real operations may need write scope. Check the provider's API docs and regenerate the key with the right scope.
"I accidentally committed my key to git"
Rotate immediately in the provider dashboard, then update the credential in NimbusOS. Treat any committed key as compromised.
"Rotation happened but now integration is failing"
The rotation re-encrypted with a new Fernet key. If the integration status changed, check the audit log for the rotation event. Uncommon but possible: the new key was not yet available in the secrets store when the integration tried to read. Retry.
Frequently Asked Questions
Can I see the plaintext of a stored credential?
No. Plaintext is never exposed through the UI or API, even to workspace owners. This is by design. If you need the plaintext (for example, to use the same key elsewhere), retrieve it from the provider's dashboard, not from NimbusOS.
Is there a way to use a single credential across multiple workspaces?
Not directly. For agencies with shared enrichment accounts, you can paste the same key into each workspace. Each workspace encrypts it separately. Usage will draw from the same provider account but the NimbusOS credential records are independent.
Does NimbusOS ever proxy credential calls through its own infrastructure?
Yes, for outbound calls to the provider. The call originates from a NimbusOS server, authenticated with your credential. The call does not go through your network. This has implications for IP allowlists at the provider side; NimbusOS's egress IP range is published on request.
How does BYOK work for webhooks inbound from providers?
Inbound webhooks verify signatures using a shared secret. The secret is treated as a credential and stored with the same encryption model. You configure the secret when you set up the webhook at the provider side.
What to Read Next
Useful next pages after this one: Integration Overview for the full integration landscape, CRM Integrations for OAuth credential flows, and Webhooks for the signing key management on inbound events.