Credentials and sources

A credential belongs to your account, not to one workspace. A source uses one credential to read one cloud account, subscription, project or cluster, and several sources can share a credential.

You usually create credentials without thinking about it: Add a Source stores the credential you paste and creates the source in one step, or reuses one you already added (see Reuse a credential). To see them all, open Cloud Connections. The Credentials section lists each credential's Name, Provider, Kind, Secret Store Key and Created date. Select a credential to open its details.

The kind says how Kumo.io signs in:

The provider pages explain each method: AWS, Azure, Google Cloud and Kubernetes.

Reuse a credential

To connect another account, subscription, project or cluster with a credential you already added, you don't paste it again:

1. Open Cloud Connections and select Add a Source, then pick the provider.
2. When your account has a credential for that provider, Add a Source shows Choose a Credential. Pick Use an Existing Credential.
3. Under Pick the Credential, choose it in Credential. Nothing new is stored.
4. If the credential can see several accounts, subscriptions or projects, name the one to connect (for Kubernetes, the cluster is required). Otherwise Kumo.io connects the first one it finds.
5. Pick the Workspace, then select Connect Source.

Test Connection isn't offered here: the credential was checked when it was added, and its details page has its own check (see Test a credential).

Pasted credentials and references

Kumo.io holds a credential in one of two ways.

• Pasted. You paste the secret (an access key, a client secret, a key file, a kubeconfig) into Add a Source or the CLI. Kumo.io encrypts it into its own secret store and keeps only a reference to it, shown as the Secret Store Key.
• Reference (self-hosted). You keep the secret in your own store, and the credential only records where to find it. Kumo.io reads it each time it syncs. Self-hosted Kumo.io can read references to an environment variable of the Kumo.io process (env:VARIABLE) or a 1Password item through the 1Password CLI (op://vault/item/field).

On kumo.io, every credential is pasted. References to your own stores aren't available on hosted Kumo.io.

Kumo.io refuses a reference that looks like a secret itself, such as an access key ID or a private key pasted into the reference field, so a secret can't end up stored in the clear by mistake.

How pasted secrets are protected

• Encrypted at rest. Each secret is encrypted with AES-256-GCM before it is written to Kumo.io's database. Each account can only read its own secrets.
• Never returned. No API response, page or export contains the secret. Credential details show only the name, kind, reference and creation date.
• Erased when replaced. Rotating a credential erases its old secret, and deleting a credential erases its secret.
• Kept out of logs. The secret is never logged, echoed or written to the audit log.

On kumo.io, the encryption key is held outside the database. A self-hosted deployment creates its own encryption key in the database the first time it starts. To hold the key outside the database instead, which is stronger, set KUMO_PG_SECRETS_KEK to a base64-encoded key. Use kumo encryption rewrap to re-encrypt stored secrets onto the active key after you change keys.

What kumo.io accepts

Hosted Kumo.io only signs in with credentials that belong to your own accounts:

• No runtime identity. Hosted Kumo.io never crawls as its own AWS identity, so the Runtime identity method isn't offered. Kumo.io also refuses a role in its own AWS account.
• Pasted secrets only. As above, a hosted credential always lives in Kumo.io's encrypted store.

A credential that breaks these rules is refused when you create it, before anything is stored, with a message saying that the credential kind is not available on this deployment, or that the reference's scheme isn't allowed.

Test a credential

Open the credential from Cloud Connections and select Test Connection. Kumo.io runs a live check against the provider and shows the result with its findings, or "No findings — the credential checks out." Kumo.io also checks credentials regularly on its own; see Credential health.

When you add a source, Test Connection in Add a Source checks the credential before anything is saved.

Rotate a credential

Rotate a credential when its secret changes, for example when an Azure client secret is about to expire, or you replace an access key. Rotating keeps the same credential, so every source that uses it picks up the new secret on its next sync, without being edited.

1. Open the credential from Cloud Connections and select Rotate….
2. Enter the new secret. Rotate Credential asks for the same fields as Add a Source does for that kind: the new access key and secret access key, the new client secret, the new key file or kubeconfig. For a cross-account role, enter the Role ARN and the External ID your role's trust policy requires; Kumo.io never shows the stored one. The external ID must be the one this credential already uses or the one Kumo.io issued for your account (shown in Add a Source). Kumo.io refuses any other external ID, and a role without one.
3. Select Rotate.

Kumo.io encrypts the new secret into its secret store and erases the old one from it. The Secret Store Key changes; the credential's name and ID don't.

On a self-hosted installation you can instead select Use a Secret Reference and enter a reference your installation already reads (env:VARIABLE or op://vault/item/field). Kumo.io never erases a secret held in your own store.

Apart from a cross-account role's external ID, rotating doesn't check the new secret. Select Test Connection afterwards. Rotating also doesn't revoke the old secret with your cloud provider: do that once the new one works.

Delete a credential

Open the credential from Cloud Connections, select Delete…, then Delete to confirm.

Kumo.io refuses to delete a credential while any source still uses it. The message names how many sources still use it. Delete or archive those sources first, then delete the credential.

Deleting a credential stops Kumo.io from using it and erases its pasted secret from Kumo.io's secret store. Kumo.io keeps a record that the credential existed, without the secret, so archived sources and the audit log still name it. A secret held in your own store (a reference) is left where it is.

Deleting doesn't revoke anything at your cloud provider, so also delete the role, access key, client secret or service-account key you created for Kumo.io.

Audit trail

Creating, rotating and deleting a credential are recorded in your account's audit log, with who did it and when. The secret itself is never part of the record.

From the CLI and API

• kumo source connect pastes a credential and creates its source in one step. See the provider pages for examples.
• kumo credential create --display-name <name> --credential-kind <kind> --secret-ref <ref> registers a reference credential, for example --secret-ref env:KUMO_AWS_CRED_JSON.
• kumo credential health checks and reports on credential health.

There are no CLI commands to rotate, list or delete credentials yet. Use the web interface or the API.

The API manages credentials under /v1/accounts/{accountId}/source-credentials: list and create (GET, POST), read and delete one (GET, DELETE on /{credentialId}), and rotate (POST /{credentialId}/rotate with the new secret as secretMaterial, or, self-hosted, a new secretRef). See the API reference.