Skip to main content
Everything that reaches Infisical does so as an identity. There are two kinds of identities:

User Identities

People who sign in through the dashboard or the CLI.

Machine Identities

Applications, pipelines, and clusters that authenticate with no person present.
Authenticating and being authorized are two separate steps. Your permissions are decided by the roles and policies you’ve been given, which are covered under access control:

Access Control

Roles, attributes, and approvals that decide what an identity may do.

​
Calculating identity counts

Understanding how to calculate your identity requirements helps with capacity planning and licensing.

​
User identities

User identity count is straightforward—it equals the number of human users who need access to Infisical. This includes developers, DevOps/platform engineers, security administrators, and any other team members requiring direct Infisical access.
User identities map 1:1 with people. If you have 50 engineers who need Infisical access, that’s 50 user identities.
An agent operated one-to-one by a person, such as a local coding assistant, authenticates as that person and doesn’t add to your identity count. See AI agent identities for the full breakdown.

​
Machine identities

If you’re familiar with cloud provider IAM concepts, Infisical machine identities work the same way: Just as you don’t create a new IAM role for every EC2 instance or a new service account for every VM, you don’t create a new Infisical machine identity for every machine. Instead, machine identities are permission-based, not machine-based—they represent a unique set of access permissions that can be shared across multiple workloads.
Key principle: If multiple machines require identical permissions to the same secrets, they share a single machine identity—just like multiple EC2 instances can assume the same IAM role.

​
How to calculate machine identities

Consider these factors when determining your machine identity count:

​
Examples

Scenario: 10 VMs in your production environment all need read access to the same database credentials in prod/database/*.Machine identities needed: 1All VMs share the same permission requirements, so they authenticate using a single machine identity. This is equivalent to having 10 EC2 instances assume the same IAM role.
Scenario: You have application servers for staging and production, each needing access to their respective environment’s secrets.Machine identities needed: 2
  • 1 identity for staging servers → access to staging/*
  • 1 identity for production servers → access to prod/*
Even if you have 20 staging servers and 50 production servers, you only need 2 identities—just as you’d have separate IAM roles for staging vs. production access.
Scenario: Your CI/CD system has:
  • Build pipelines that need read access to artifact registry credentials
  • Deployment pipelines that need read access to cloud provider secrets and database URLs
  • Security scanning pipelines that need access to scanning tool API keys
Machine identities needed: 3Each pipeline type has distinct permission requirements, warranting separate identities.
Scenario: Your application runs across AWS EKS, GCP GKE, and Azure AKS, but all clusters need identical access to the same secrets.Machine identities needed: 1A single machine identity can have multiple authentication methods configured simultaneously. You would attach AWS IAM Auth, GCP IAM Auth, and Azure Auth to the same identity, allowing workloads from any cloud to authenticate to the same permission set.
Scenario: You have 15 microservices:
  • 10 services need access only to shared infrastructure secrets (Redis, message queue)
  • 3 services need access to payment processing secrets
  • 2 services need access to third-party integration API keys
Machine identities needed: 3Group services by their secret access requirements, not by the number of service instances or replicas.

​
AI agent identities

Agents follow the same rule as any other workload: identities are permission-based, not process-based. What decides whether an agent consumes a machine identity is how it authenticates, not that it’s an agent or where it runs.
Running a coding agent on your own computer doesn’t consume a machine identity. With the Local Agent Proxy there is no machine identity to create: you log in once, the run authenticates as you, and its activity is attributed to your account. Machine identities are for agents that run standalone, outside any one user’s session.
A scoped machine identity can be narrower than the person operating the agent, which is why PAM recommends running a sensitive or untrusted agent as its own identity even when someone is watching it. That isolation is a deliberate least-privilege choice, and every identity you create for it counts.

​
Scoping agent identities

For agents that authenticate as themselves, scope identities by purpose and permission set, not by agent instance, run, container, or VM.
In a Standalone Agent Proxy deployment there are two kinds of identity. Each agent authenticates to the proxy with its own machine identity, which holds only the Proxy permission on the services that agent uses. The proxy has a separate identity of its own, and that is the one that fetches the secrets its proxied services reference from Infisical. Count the proxy’s identity on top of one identity per agent permission set.
Scenario: 40 engineers each run a coding agent on their laptop with infisical secrets agent-proxy run.Machine identities needed: 0Each run authenticates as the engineer who started it, so the access is already accounted for by their 40 user identities. A machine identity isn’t required here. If you later decide a particular agent should run under its own scoped identity, that identity counts, even though the agent still runs locally.
Scenario: You run two always-on Slack agents in your own infrastructure:
  • A recruitment agent scoped to ATS and calendar access
  • An engineering agent scoped to CI and observability access
Machine identities needed: 2Each agent has a distinct purpose and a distinct permission set. If you later add three more recruitment agents that need the same access, they can all share the recruitment identity, so the count stays at 2.
Scenario: An agent that sorts incoming support tickets runs as 25 concurrent workers, each spawning short-lived runs in its own container.Machine identities needed: 1Runs, containers, and replicas don’t increase the count. All workers execute the same logic against the same secrets, so they share one identity, the same way 10 VMs with identical access do.
Scenario: Two remote agents with different permission sets run behind one Standalone Agent Proxy.Machine identities needed: 3Two for the agents, since each authenticates to the proxy with its own machine identity, plus one for the proxy, which uses a separate identity to fetch secrets back from Infisical.

​
Best practices

While consolidating machine identities reduces management overhead, more granular identities provide stronger security through least-privilege access and reduced blast radius. The right balance depends on your security requirements.

​
When to use separate identities

Create distinct machine identities to enforce security boundaries between:
Blast radius consideration: If a machine identity is compromised, an attacker gains access to everything that identity can access. Design your identity boundaries around “what’s the worst case if this credential leaks?”

​
When consolidation is acceptable

Sharing a machine identity across workloads is appropriate when:
  • Replicas of the same application — Multiple pods/instances running identical code with identical secret needs
  • Stateless workers — Horizontally scaled workers performing the same job
  • Tightly coupled services — Services that are deployed together and share a security boundary

​
Kubernetes best practices

For Kubernetes environments, we recommend mapping machine identities at the namespace level:
1

One identity per namespace

Create a machine identity for each Kubernetes namespace that needs secrets. This aligns with Kubernetes’ native isolation model and simplifies RBAC management.
2

Leverage Kubernetes Auth

Use Kubernetes Auth to bind machine identities to specific ServiceAccounts and namespaces. This ensures only pods in the authorized namespace can authenticate.
3

Scope Agent Injector or Operator access

When using the Infisical Agent Injector or Operator, configure namespace-scoped access rather than cluster-wide permissions.
Scenario: You have a shared Kubernetes cluster with three teams, each with their own namespace:
  • team-payments — handles payment processing
  • team-platform — runs shared infrastructure (API gateway, service mesh)
  • team-analytics — runs data pipelines
Recommended approach: 3 machine identitiesThis ensures that a compromised pod in team-analytics can’t access payment processing credentials, even if an attacker gains cluster-level access.

​
Quick assessment questions

When planning your machine identity strategy, consider:
  1. What’s the blast radius? If this identity is compromised, what secrets are exposed? Design boundaries to limit damage.
  2. Are these workloads in the same trust boundary? Applications that shouldn’t access each other’s data need separate identities.
  3. What are your compliance requirements? Regulated workloads may require documented isolation from non-regulated systems.
  4. What’s your authentication topology? A single identity can authenticate from multiple sources (Kubernetes + AWS IAM + GCP), so multi-cloud doesn’t necessarily mean multiple identities—but multi-tenant does.
  5. How does this agent authenticate? An agent that authenticates as a person inherits that person’s permissions, while an agent that authenticates as itself needs its own identity scoped to its purpose.
Bottom line: When in doubt, err on the side of more identities. The operational overhead of additional identities is minimal compared to the security benefits of proper isolation.