How to Keep a Vector Database Workspace Workflow Clean When Onboarding New Developers and Service Accounts

Onboarding is where access debt starts. A new developer joins and needs access immediately, so they get the shared key that already exists. A new service account is needed and someone copies the credentials from an existing one. Decisions that feel like minor shortcuts in the moment accumulate into a workspace where nobody knows who has what access, rotating a key is a multi-hour coordination problem, and removing access for someone who left requires tracking down which credentials they were using and hoping nothing else depended on them.

A clean onboarding workflow prevents this. It is not complicated — it just requires making the same deliberate choices each time someone new joins or a new service account is needed, rather than taking the path of least resistance.

What Onboarding Actually Creates

Every developer and every service account that gets added to a vector database workspace creates two things: a set of credentials and a set of expectations about what those credentials can do.

Credentials that are scoped, named, and documented cleanly are easy to revoke, easy to audit, and easy to hand off when responsibilities change. Credentials that were created quickly and informally — shared from an existing key, named generically, without documented role assignments — are fragile. They tend to accumulate access they should not have, resist rotation because their scope is unclear, and require investigation rather than just a console action when something needs to change.

The onboarding workflow is the moment to get this right. Once credentials exist and services depend on them, correcting mistakes is significantly more disruptive than making the right choices upfront.

Individual Credentials for Every Actor

The single most important rule for clean onboarding is that every developer and every service account gets its own credential. Not a copy of a shared credential — a distinct one that belongs to that person or service and no other.

This has several practical effects that compound over time. It makes revocation precise: offboarding a developer means disabling their credential, not rotating a shared one and updating every service simultaneously. It makes auditing possible: when access logs show an unusual pattern, the credential in question identifies a specific actor. It makes permission assignment meaningful: each credential can be scoped to exactly the access needed, rather than inheriting the broadest scope of whatever existing credential was copied.

Naming and Documentation

Credentials should be named to identify the actor, not the purpose. alice-smith is better than read-only-key. ingestion-pipeline-staging is better than staging-key-2. Names that identify the actor make it possible to answer the question “which credentials does this person or service have?” without investigating further.

Document each credential as part of the onboarding process: who it belongs to, what role it has, when it was created, and which environments it is valid for. This documentation does not need to be elaborate — a shared document or a comment in the credential name is often enough. What matters is that it exists and is updated when credentials change.

Service Account Onboarding

Service accounts are often treated as afterthoughts in onboarding processes designed around human developers. They get the same credential as the developer who set them up, or a freshly created key with admin permissions because it was easier than figuring out the minimum required access.

Service accounts should follow the same rules as developer accounts: their own credential, named for the service, scoped to exactly the access the service needs. The difference is that service account credentials tend to be longer-lived and harder to rotate — they are embedded in deployment configurations, environment variables across multiple environments, and sometimes in infrastructure that has a slow change cycle.

This is precisely why getting them right at creation matters more than with developer accounts. A service account with unnecessarily broad permissions that is difficult to rotate is a persistent risk. A service account with minimum permissions that is clearly documented is a manageable one.

Environment Separation as Part of Onboarding

New developers should be onboarded with credentials specific to their starting environment. A developer working on a new feature does not need production credentials on their first day. Access to production environments should be provisioned deliberately, separately, and when there is an actual need — not as part of default onboarding.

This requires separate credentials per environment as a matter of practice. When a developer eventually needs production access, granting it is a deliberate action. When they move off the project, removing it is equally deliberate.

Weaviate: Clean Onboarding in the Console

Onboarding a New Developer

When a new developer joins:

1. Open the Weaviate Cloud console and select the appropriate cluster (start with development, not production)
2. Go to Cluster details → API Keys → New key
3. Name the key with the developer’s identifier — alice-smith-dev rather than something generic
4. Assign the minimum role appropriate for their work — viewer for read-only access, a custom role scoped to specific collections for write access, admin only when genuinely required
5. Copy the key and share it through a secure channel
6. The developer stores it as an environment variable:

export WEAVIATE_URL="replaceThisWithYourRESTEndpointURL"
export WEAVIATE_API_KEY="replaceThisWithYourAPIKey"

1. They verify the connection works before starting any work

Onboarding a Service Account

Service account onboarding follows the same steps with additional care on role scoping. Query services get read access to the collections they query. Ingestion pipelines get write access to the collections they write to. Nothing gets admin access unless it genuinely administers the cluster.

For v1.30+ clusters, use the database user management API for programmatic service account creation if you are automating onboarding:

user_api_key = client.users.db.create(user_id="ingestion-pipeline-staging")
client.users.db.assign_roles(
    user_id="ingestion-pipeline-staging",
    role_names=["ingestion_role"]
)

Custom Roles for Clean Permission Assignment

Define roles that map to actual functions before onboarding begins, so new credentials can be assigned to an existing role rather than requiring a permission decision each time:

• A read-only role for analysts and read-heavy services
• A write role scoped to ingestion collections for data pipelines
• A search role scoped to query collections for application services
• Admin access reserved for a small named group

When a new developer or service account arrives, the question is “which role fits?” not “what permissions should I assign?”

Environment Separation in the Console

The Clusters sidebar shows all environments. Onboard developers to the development cluster first. Grant staging access when they are actively working on pre-production validation. Grant production access when there is a specific operational need.

Each cluster has its own roles and keys — production credentials never overlap with development credentials unless explicitly shared across clusters.

Monitoring Who Has Access

The console’s Cluster details → API Keys view shows all active keys for a cluster, their names, and their assigned roles. Review this periodically — especially after team changes — to ensure no stale credentials remain active and no access has drifted beyond its original scope.

The Onboarding Checklist