Open Kortyx on GitHub

Kortyx Studio Credentials and Secrets

Updated 17 minutes ago • August 2, 2026

Studio separates human sign-in, SDK ingestion, internal reads, database access, and API-key verification. These credentials have different consumers and must not be reused interchangeably.

Credential roles

CredentialConsumerStored as raw value in Kortyx PostgreSQL?If rotated
Basic Auth username/passwordHuman browserNoExisting browser sign-in stops working
Telemetry write keyServer-side Kortyx SDK producerNoProducers using the old key receive 401
Studio read keyStudio serverNoStudio cannot load data until updated
API-key pepperTelemetry API and database jobNoChanging it invalidates every API key
PostgreSQL credentialsAPI and database jobProvider-managedDatabase and workloads must rotate together

Kortyx stores the API key identifier, a one-way HMAC verifier, Project ownership, scopes, expiry, revocation state, and usage metadata. The complete ktyx_... value belongs only in the secret store used by its consumer.

Why both a database record and a secret manager? The secret manager protects the raw credential. PostgreSQL holds the verifier and authorization policy needed to check that credential without retaining a reusable key.

Local credentials

The CLI creates and stores local values privately under ~/.kortyx/studio.

Print the current connection details:

npx kortyx studio credentials

Rotate the browser password, telemetry key secret, and Studio key secret:

npx kortyx studio credentials --rotate

The CLI updates the private environment atomically, applies the new key verifiers, recreates the affected services, and attempts to restore the previous values if the application fails.

Rotation invalidates the previous telemetry key immediately. Update and restart every server-side SDK producer using that key. PostgreSQL credentials and the API-key pepper are deliberately preserved.

Generate credentials for a deployment

npx kortyx studio credentials --generate

This command prints a fresh deployment credential set without writing local state. Store the output immediately; it cannot be retrieved later.

Use the secret facility appropriate to the target:

PlatformRecommended destination
AWSSecrets Manager or an approved equivalent
Google CloudSecret Manager
KubernetesExternal secret integration or a tightly controlled Secret
Controlled single serverA root/operator-readable environment file outside the repository

Do not put secret values in Terraform source, generated manifests, image layers, CI logs, tickets, chat, or screenshots.

Remote key rotation

The initial deployment contract replaces an API-key secret while retaining its key ID:

  1. Preserve the prefix through the final underscore, such as ktyx_live_<key-id>_.
  2. Generate a new random secret of at least 32 bytes and append it.
  3. Update the consumer's secret-manager value.
  4. Run kortyx-studio-db bootstrap with the new complete key.
  5. Roll or restart the affected consumer.
  6. Verify that the new key works and the previous key receives 401 Unauthorized.

Reusing the key ID replaces its verifier. For the Studio read key, run bootstrap before recreating Studio. For one telemetry write key shared by multiple applications, coordinate a maintenance window; overlapping remote keys are not yet managed through an Admin API.

Do not rotate the pepper during routine key rotation. A new pepper makes every existing API-key verifier unusable.

Backup and incident response

Back up PostgreSQL and deployment secret references as one recovery set. A database backup without its matching pepper cannot verify the existing API keys.

If a raw API key is exposed:

  1. replace its secret under the same key ID;
  2. rerun bootstrap;
  3. roll the affected consumer;
  4. verify the new key; and
  5. verify the exposed value now receives 401 Unauthorized.

Treat captured telemetry backups according to the sensitivity of any input or output content your producers chose to export.