Manage tenants, identities, and credentials

A Flowcore tenant is both an ownership boundary and a security boundary. Data cores, IAM resources, users, API keys, variables, secrets, quotas, and Data Pathways are scoped to a tenant.

Design tenant access before applications reach production. Retrofitting identity ownership and least privilege after broad keys have spread across workloads is difficult and risky.

Use tenants as governance boundaries

A tenant should represent a boundary that needs independent administration, credentials, policy, or resource ownership.

Before creating or joining resources to a tenant, document:

• The organization or product that owns it
• Its environment, such as development or production
• Tenant administrators
• Approved human users
• Approved service identities
• Data classification and regional requirements
• Credential rotation responsibility
• Incident-response contacts

Do not create a tenant merely as a temporary folder. Moving resources and event history across tenant boundaries is a migration.

Separate environments

Development, staging, and production should not share application credentials.

Use separate tenants where the governance model requires hard isolation, or use another approved environment boundary with independently scoped resources and policies.

A development key must not be able to publish, query sensitive history, or administer pathways in production.

Keep environment identity visible in tenant names, CLI profiles, secret paths, dashboards, and deployment configuration.

Manage human users explicitly

Human administrators authenticate through OAuth and receive bearer tokens. Add users only to tenants where they have an active responsibility.

Grant routine access through reusable roles rather than direct broad policies for every person. Reserve tenant administration and destructive permissions for a small, reviewed group.

When a user changes team or leaves the organization:

1. Remove or update role associations promptly.
2. Revoke tenant membership that is no longer needed.
3. Review policies created or owned by the user.
4. Rotate shared credentials the user could access.
5. Preserve audit records rather than deleting evidence.

Do not rely only on identity-provider deactivation if Flowcore associations or long-lived credentials remain.

Use OAuth bearer tokens for user operations

Bearer tokens represent an authenticated user or OAuth client. They are required for selected administrative, GraphQL compatibility, and AI Agent Coordinator operations.

A backend using a user's token should obtain it through the approved OAuth flow and refresh it safely. Do not copy a token from browser storage into a long-running service.

Bearer tokens are short-lived credentials. A 401 may mean expiration, wrong audience, invalid issuer, or an endpoint that does not allow bearer mode.

Use API keys for applications

Applications should use dedicated API keys rather than a person's token.

Create one key for one service and environment. Good key metadata identifies:

• Service name
• Environment
• Owner
• Purpose
• Expected permissions
• Creation date
• Rotation schedule
• Deployment or secret path

Avoid a single “tenant key” shared by every workload. Shared broad keys make rotation disruptive and prevent attribution during an incident.

Create an API key with the SDK

A trusted administrative client can create a named key:

import {
  ApiKeyCreateCommand,
  FlowcoreClient,
} from "@flowcore/sdk"
 
const adminClient = new FlowcoreClient({
  getBearerToken: getAdminBearerToken,
})
 
const created = await adminClient.execute(
  new ApiKeyCreateCommand({
    tenantId,
    name: "orders-api-production",
    description: "Publishes order events from the production Orders API",
  }),
)

The returned object includes the key value at creation. Store it immediately in a secret manager. Do not print the result object to logs or expect to retrieve the same secret later.

List operations should expose metadata rather than plaintext secrets.

Bind permissions before deployment

Creating a key does not define what it may do. Attach roles or policies that cover only the required actions and resource scope.

An event producer may need ingestion rights for one data core and selected event types. It does not need IAM administration, sensitive-data reads, pathway restart, or resource deletion.

A provisioning job may need resource create and update permissions but no access to event payloads.

Test the exact application workflow using the intended key. Do not infer effective access only from the policy authoring screen or manifest.

Store credentials safely

Application keys belong in a managed secret store, such as:

• A cloud secret manager
• Kubernetes Secrets protected by the cluster's encryption and RBAC controls
• A deployment platform's encrypted secret facility
• A dedicated secrets system such as Vault

Do not store keys in:

• Git repositories
• Docker images
• Public or browser environment variables
• Event payloads or metadata
• Ordinary tenant variables
• Shell history
• Logs and error reports
• Shared documents or tickets

Limit who and what can read the deployment secret. Platform administrators do not automatically need access to every application key value.

Inject credentials at runtime

Read the key from a server-side environment or secret mount:

const apiKey = process.env.FLOWCORE_API_KEY
 
if (!apiKey) {
  throw new Error("FLOWCORE_API_KEY is required")
}
 
const client = new FlowcoreClient({ apiKey })

Fail clearly when the secret is missing. Do not fall back to a development key or a broad default credential.

Avoid including key prefixes or fragments in routine logs. If operators need to identify a key, use the non-secret key ID or configured name.

Rotate API keys without downtime

A safe rotation uses an overlap period:

1. Create a replacement key with equivalent reviewed policy.
2. Store it under a new secret version.
3. Deploy consumers using the replacement.
4. Verify successful Flowcore operations from every replica and job.
5. Confirm the old key is no longer used.
6. Delete or revoke the old key.
7. Record completion and the next rotation date.

Do not edit an old key description and treat that as rotation. The secret value must change.

For applications that cannot accept two credentials simultaneously, rotate through the deployment platform's secret-version and rollout mechanism.

Respond to suspected exposure

If a key may be exposed:

1. Create and deploy a replacement immediately when continuity is required.
2. Revoke the exposed key.
3. Identify the key's effective permissions and resource scope.
4. Review event writes, reads, IAM changes, pathway operations, and destructive requests during the exposure window.
5. Rotate downstream secrets accessible to the workload if necessary.
6. Remove the leaked value from logs, artifacts, or history where possible.
7. Preserve incident evidence without preserving the plaintext credential in reports.

Do not wait for the normal rotation date.

Audit credential inventory

Periodically compare listed keys with deployed workloads and owners.

Investigate keys that have:

• No current owner
• No recent usage but broad permissions
• Ambiguous names
• Unknown deployment locations
• Overlapping responsibilities
• Old creation dates
• Access beyond the service's current design

Remove unused credentials. Disabling one application configuration while leaving its key active does not reduce platform risk sufficiently.

Keep interactive and automation access separate

Human operators should use OAuth through the CLI or trusted administrative tools. CI and services should use dedicated automation identities and protected environments.

Do not run production apply or delete commands under a developer's long-lived personal token in shared CI.

Continue with Design Flowcore IAM access for roles, policies, bindings, permissions, and resource scope.