> ## Documentation Index > Fetch the complete documentation index at: https://infisical.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Identity and access > Understand who and what can reach Infisical, how each one proves it, and what they're allowed to do. Everything that reaches Infisical does so as an identity. There are two kinds of identities: > [card] [User Identities](https://infisical.com/docs/documentation/platform/identities/user-identities.md) > > People who sign in through the dashboard or the CLI. > [card] [Machine Identities](https://infisical.com/docs/documentation/platform/identities/machine-identities.md) > > 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: > [card] [Access Control](https://infisical.com/docs/documentation/platform/access-controls/overview.md) > > 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. > [!TIP] > > 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](#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: | Cloud Provider | Equivalent Concept | | - | - | | AWS | IAM Roles | | GCP | Service Accounts | | Azure | Service Principals | | Kubernetes | ServiceAccounts | 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. > [!NOTE] > > **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: | Factor | Impact on Identity Count | | - | - | | **Unique permission sets** | Each distinct combination of project access + environment access + secret paths = 1 identity | | **Number of machines** | Has no effect on identity count if permissions are identical | | **Authentication methods** | A single identity can authenticate via multiple methods (AWS IAM, Kubernetes, GCP, Azure, etc.) simultaneously | #### Examples > [accordion] Example 1: Multiple VMs with identical access > > **Scenario**: 10 VMs in your production environment all need read access to the same database credentials in `prod/database/*`. > > **Machine identities needed**: **1** > > All 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. > [accordion] Example 2: Separate environments > > **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. > [accordion] Example 3: CI/CD pipelines with different scopes > > **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**: **3** > > Each pipeline type has distinct permission requirements, warranting separate identities. > [accordion] Example 4: Multi-cloud authentication > > **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**: **1** > > A 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. > [accordion] Example 5: Microservices architecture > > **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**: **3** > > Group 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. | How the agent authenticates | Counts as | | - | - | | **As a person.** An agent started with the [Local Agent Proxy](https://infisical.com/docs/documentation/platform/agent-proxy/local-agent-proxy) authenticates as the user who ran `infisical login`, so the agent-to-user ratio is 1:1. | The operator's existing user identity. No machine identity. | | **As itself.** An agent that runs perpetually in its own environment, on a schedule, or unattended, plus any agent you deliberately scope to its own identity, authenticates with its own [machine identity](https://infisical.com/docs/documentation/platform/identities/machine-identities.md). | One machine identity per unique permission set. | > [!NOTE] > > Running a coding agent on your own computer doesn't consume a machine identity. With the [Local Agent Proxy](https://infisical.com/docs/documentation/platform/agent-proxy/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. > [!TIP] > > 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](https://infisical.com/docs/documentation/platform/pam/ai-agents/unattended.md) 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. | Grouping | Identities needed | | - | - | | Multiple instances or runs of the same agent, with the same access | 1 | | Two agents serving different functions, such as recruitment and engineering | 2 | | One agent that needs access to two different security tiers | Consider 2, scoped per tier | | A [Standalone Agent Proxy](https://infisical.com/docs/documentation/platform/agent-proxy/standalone-agent-proxy) in front of those agents | Add 1 for the proxy itself | > [!NOTE] > > 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](https://infisical.com/docs/documentation/platform/agent-proxy/proxied-services) reference from Infisical. Count the proxy's identity on top of one identity per agent permission set. > [accordion] Example 6: Local coding agents > > **Scenario**: 40 engineers each run a coding agent on their laptop with `infisical secrets-manager agent-proxy run`. > > **Machine identities needed**: **0** > > Each 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. > [accordion] Example 7: Standalone agents with different purposes > > **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**: **2** > > Each 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. > [accordion] Example 8: Horizontally scaled agent workers > > **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**: **1** > > Runs, 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. > [accordion] Example 9: Remote agents behind a Standalone Agent Proxy > > **Scenario**: Two remote agents with different permission sets run behind one [Standalone Agent Proxy](https://infisical.com/docs/documentation/platform/agent-proxy/standalone-agent-proxy). > > **Machine identities needed**: **3** > > Two 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: | Boundary | Why Separate? | | - | - | | **Different applications** | Prevents one compromised app from accessing another app's secrets | | **Security tiers** | Payment processing, PII handling, and general app secrets should be isolated | | **Trust levels** | Internal tools vs. customer-facing services vs. third-party integrations | | **Compliance scopes** | SOC 2, PCI-DSS, or HIPAA-regulated workloads may require isolation | > [!WARNING] > > **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](https://infisical.com/docs/documentation/platform/identities/kubernetes-auth.md) 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](https://infisical.com/docs/integrations/platforms/kubernetes-injector.md) or [Operator](https://infisical.com/docs/integrations/platforms/kubernetes/overview), configure namespace-scoped access rather than cluster-wide permissions. > [accordion] Example: Multi-tenant Kubernetes cluster > > **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 identities** > > | Identity | Namespace | Access | > | - | - | - | > | `k8s-payments` | `team-payments` | Payment secrets only | > | `k8s-platform` | `team-platform` | Infrastructure secrets only | > | `k8s-analytics` | `team-analytics` | Analytics pipeline secrets only | > > This 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. > [!NOTE] > > **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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.