Security Baseline

This section introduces the security best practices for building on qibdo. They apply across every service; an individual service may add more on top, but these are the platform-wide defaults worth following from the start.

Authentication and access

Every request to a qibdo API carries a bearer token, and access is decided by IAM: the token identifies a principal, and IAM resolves what that principal is allowed to do. There are two kinds of principal, and they map to two token patterns.

• Personal tokens represent a human. You obtain one by authenticating with your credentials, and you use it for interactive work: the CLI, your own scripts, exploring the API. These tokens are opaque and server-side, so they can be revoked the moment you need to.
• Service accounts represent a machine, not a person. They are the right identity for automation, CI, and service-to-service traffic, never a human’s personal token. Service-account access is carried by short-lived JSON Web Tokens (JWTs) that are verified by signature and expire quickly, so a leaked token is only useful for a small window.

Pick the identity that matches the caller: a person doing interactive work uses a personal token; anything unattended (a pipeline, a scheduled job, another service) should run as a service account scoped to only what it needs. IAM is the source of truth for identities and tokens, including their lifetimes; see its overview for the mechanics.

In every example, script, and integration, reference a token by a named placeholder ($QIBDO_API_TOKEN), never by its literal value.

Use Vault for secrets and keys

Don’t build your own secret storage. Vault is qibdo’s secrets and key-management service, and using it is what keeps sensitive material out of your source, your config, and your container images.

• Store secrets in Vault. Application secrets, API keys, and certificates belong in Vault, where they are versioned, not in source or in environment files you commit.
• Prefer short-lived, dynamic credentials. Instead of long-lived database or cloud credentials, have Vault mint them on demand with a time-to-live (databases, AWS, GCP, Azure, SSH, Kubernetes), so they expire on their own rather than lingering.
• Rotate keys. Rotate encryption keys in Vault; a new key version becomes the default, and existing data can be re-encrypted forward without exposing plaintext.
• Encrypt application data. Use Vault’s encryption keys to encrypt and decrypt data so your application never handles raw key material.

Revoke on exposure

Treat every credential as revocable, and act immediately on suspected exposure.

• Personal tokens can be revoked through IAM (/iam/v1/tokens:revoke); revocation takes effect at once. Service-account JWTs are short-lived and expire on their own, which keeps the exposure window small.
• Dynamic credentials and their leases can be revoked in Vault, one at a time or in bulk by prefix for incident response.
• Issued certificates can be revoked and appear on the certificate revocation list.

Because examples reference tokens by placeholder rather than by value, rotating or revoking a credential is a configuration change, not a code change.

Least privilege

Grant the smallest set of permissions that gets the job done, at the narrowest scope. qibdo uses role-based access control (RBAC) through IAM:

• Permissions are granular and named service.resource.action (for example compute.vm.create).
• Roles bundle permissions. Use the predefined roles where they fit, and create a custom role when you need a specific, smaller set.
• Bindings grant a role to a principal at a scope. Bind at the narrowest scope that works, a single workspace or group, rather than at the organisation or platform level, where one grant covers everything beneath it.
• For automation, give each service account its own binding with the minimum permissions, and prefer a custom role scoped to one workspace over a broad predefined role at the organisation.

See the IAM overview for identities, roles, and bindings.