Machine identities

Concept

An Infisical machine identity is an entity that represents a workload or application that require access to various resources in Infisical. This is conceptually similar to an IAM user in AWS or service account in Google Cloud Platform (GCP). Each identity must authenticate with the Infisical API using a supported authentication method like Token Auth, Universal Auth, Kubernetes Auth, AWS Auth, Azure Auth, or GCP Auth to get back a short-lived access token to be used in subsequent requests. Organization Identities

Key Features:

Role Assignment: Identities must be assigned roles. These roles determine the scope of access to resources, either at the organization level or project level.
Auth/Token Configuration: Identities must be configured with corresponding authentication methods and access token properties to securely interact with the Infisical API.
Alerting: An identity can notify your team before a credential expires or whenever one of its auth methods changes via Alerts.

Scopes

Identities can be created either at the organization-level or the project-level. Outside of identity management and scope of operation, organization and project identities are functionally identical.

Project identities are managed at the project-level and can only operate within their respective project. Project-level identities are useful for organizations that delegate responsibility to autonomous teams via projects.
Organization identities are managed at the organization-level and can be assigned to one or more projects, as well as perform organization-level operations. Organization-level identities are useful for organizations that have cross-project operations.

Workflow

Project Identities
Organization Identities

A typical workflow for using project identities consists of three steps:

Creating the identity with a name and role in Project > Access Control > Machine Identities. This step also involves configuring an authentication method for it.
Authenticating the identity with the Infisical API based on the configured authentication method on it and receiving a short-lived access token back.
Authenticating subsequent requests with the Infisical API using the short-lived access token.

Authentication methods

To interact with various resources in Infisical, Machine Identities can authenticate with the Infisical API using:

Token Auth: A platform-agnostic, simple authentication method suitable to authenticate with Infisical using a token.
Universal Auth: A platform-agnostic authentication method suitable to authenticate with Infisical using a Client ID and Client Secret.
Kubernetes Auth: A Kubernetes-native authentication method for applications (e.g. pods).
AWS Auth: An AWS-native authentication method for AWS services (e.g. EC2, Lambda functions, etc.).
Azure Auth: An Azure-native authentication method for Azure resources (e.g. Azure VMs, Azure App Services, Azure Functions, Azure Kubernetes Service, etc.).
GCP Auth: A GCP-native authentication method for GCP resources (e.g. Compute Engine, App Engine, Cloud Run, Google Kubernetes Engine, IAM service accounts, etc.).
OIDC Auth: A platform-agnostic, JWT-based authentication method for workloads using an OpenID Connect identity provider.
SPIFFE Auth: A SPIFFE-native authentication method for workloads using JWT-SVIDs issued by SPIRE.

Identity lockout

Lockout is a feature that prevents brute-force attacks on identity login endpoints. Auth methods that support lockout include: Universal Auth, LDAP Auth. Supported auth methods have lockout enabled by default. If triggered, lockout temporarily disables the login endpoint for 5 minutes after 3 consecutive failed login attempts within a 30-second window. Lockout can be configured and disabled in the identity auth method settings.

Access token revocation

Machine identity access tokens can be invalidated before their natural expiry. An access token is revoked when you:

Call the token revoke endpoint for that token (for example, POST /api/v1/auth/token/revoke for Universal Auth).
Delete the identity, which revokes all of its active access tokens.
Remove the credential the token was issued from, such as deleting a Universal Auth client secret or removing an authentication method from the identity.

Once revoked, the token is rejected on subsequent authenticated requests and can no longer be renewed. The revocation is persisted in Infisical’s database, which is the source of truth consulted on every authentication check.

To keep authentication fast under high request volume, Infisical caches the result of each revocation check in Redis for a short period. Under normal operation a revocation takes effect immediately, because revoking a token also invalidates any cached decision for that identity.In the rare case where this cache invalidation can’t be performed (for example, a transient Redis disruption during the revoke), the database still records the revocation, but Infisical may continue to accept that exact token until its cached result expires, which takes at most 12 minutes. After that, the check is re-evaluated against the database and the token is rejected.If you need a revocation to take effect with no propagation delay even under those conditions, rotate the underlying credential (delete the Universal Auth client secret) or delete the identity, both of which invalidate the affected tokens regardless of cache state.

Alerts

An alert on a machine identity notifies your team through the channels you pick. Each alert watches one event, chosen when you create it:

Event	When it fires
Client Secret Expiration	A set number of days before a Universal Auth client secret expires, checked once a day
Auth Method Change	Right after an auth method is added, updated, or removed, or a Universal Auth client secret or Token Auth token is created, updated, or revoked

Client secret expiration

A machine identity whose credential expires unnoticed takes your workload down with it. This alert watches the Universal Auth client secrets attached to the identity and notifies your team a configurable number of days before they expire, so the credential gets rotated before anything breaks. A client secret is only monitored when its TTL is greater than 0, since one created with the default TTL of 0 never expires and has nothing to alert on. Revoked client secrets are skipped.

The alert watches the client secret, not the access tokens minted from it. Access tokens are short-lived by design and are renewed programmatically. See Universal Auth for the difference between Client Secret TTL, Access Token TTL, and Access Token Max TTL.

Auth method or credential change

Changing how a machine identity authenticates changes who can act as it. This alert fires every time any of the identity’s auth methods is added, updated, or removed, whether through the dashboard, the API, or Terraform. It covers all auth methods, from Universal Auth and Token Auth to the cloud, Kubernetes, OIDC, JWT, LDAP, SPIFFE, and TLS certificate methods. It also fires when a credential inside a method changes: a Universal Auth client secret is created or revoked, or a Token Auth token is created, renamed, or revoked. Access tokens minted by logging in with a credential aren’t credentials themselves and don’t fire it. Each notification names the auth method, the kind of change, the credential where one is involved, who made the change (a user’s email or a machine identity’s name), and when. It takes no condition and has no daily run: the notification is sent as soon as the change is saved.

Create an alert

Open the machine identity you want to monitor and select Alert in the top-right of the page to create one. An identity holds one alert, so pick the event you care about most. Create Machine Identity Alert

Field	Description
Name	A name for the alert, e.g. `ua-secret-expiry`
Description	Optional context about this alert
Event	Client Secret Expiration or Auth Method or Credential Change. The event can’t be changed after the alert is created; remove the alert and create a new one instead.
Condition	For Client Secret Expiration only: how many days before expiration to notify, as a whole number from `1` to `90`
Daily Reminder	For Client Secret Expiration only: if enabled, repeats the alert every day from the threshold until the credential expires
Enabled	Turn the alert off without deleting it

With Daily Reminder off, each credential triggers the expiration alert once. Turn it on for credentials you can’t afford to miss, and you’ll get one notification per day until the credential expires or is rotated.

Notification channels

An alert delivers through one or more channels, up to 10 per alert. Add at least one.

Channel	Configuration
Email	Pick recipients from the organization’s users and groups, up to 20 per channel. Group membership is expanded at send time.
Slack	An Incoming Webhook URL. Must be an HTTPS `hooks.slack.com` URL.
PagerDuty	An Events API v2 integration key (32-character hex string). Triggers one incident per expiring credential, deduplicated by credential. For auth method changes, repeated changes of the same kind to the same method land on one open incident.
Webhook	Any HTTPS endpoint, with an optional signing secret for verification.

Webhook payload

Webhook deliveries are CloudEvents 1.0 JSON documents. The type names the event: com.infisical.identity.authentication.expiration for a client secret expiration and com.infisical.identity.authentication.auth-method-changed for an auth method change. Every credential due for this run, or the change that fired, is listed in data.items:

{
  "specversion": "1.0",
  "type": "com.infisical.identity.authentication.expiration",
  "source": "/alerts/1bd09748-1d5b-4642-8034-f4ca88f59996",
  "id": "3f2a91c4-7e6b-4d18-9a55-08c1d4e2b7f0",
  "time": "2026-08-16T00:00:04.512Z",
  "datacontenttype": "application/json",
  "subject": "identity.authentication.expiry",
  "data": {
    "alert": {
      "id": "1bd09748-1d5b-4642-8034-f4ca88f59996",
      "name": "ua-secret-expiry",
      "resourceType": "identity.authentication",
      "condition": "7d"
    },
    "items": [
      {
        "id": "ua-client-secret:cff39386-bbe5-44eb-aecf-e2445167b497",
        "title": "ci-deploy-bot",
        "fields": [
          { "label": "Secret Name", "value": "github-actions" },
          { "label": "Secret Type", "value": "Universal Auth Client Secret" },
          { "label": "Expires", "value": "August 23, 2026 at 04:15 PM UTC" }
        ]
      }
    ],
    "metadata": {
      "totalItems": 1,
      "viewUrl": "https://app.infisical.com/organizations/18b65352-ad1e-43d5-830f-65c72245c3a3/identities/c6002a8c-4571-4660-b169-f891f4734851"
    }
  }
}

An auth method or credential change carries one item whose fields name the method, the change, the credential when one is involved, who made the change, and when. The Change field is one of Added, Updated, Removed, Credential Added, Credential Updated, or Credential Revoked:

{
  "specversion": "1.0",
  "type": "com.infisical.identity.authentication.auth-method-changed",
  "source": "/alerts/6c1e5a9b-2f4d-4b7e-8a3c-1d9e0f2b5c7a",
  "id": "a7d3e1f9-4b2c-4e8d-9f01-3c5b7a9d2e4f",
  "time": "2026-09-10T10:00:01.204Z",
  "datacontenttype": "application/json",
  "subject": "identity.authentication.auth-method-changed",
  "data": {
    "alert": {
      "id": "6c1e5a9b-2f4d-4b7e-8a3c-1d9e0f2b5c7a",
      "name": "auth-method-change",
      "resourceType": "identity.authentication"
    },
    "items": [
      {
        "id": "auth-method-change:c6002a8c-4571-4660-b169-f891f4734851:universal-auth:added",
        "title": "ci-deploy-bot",
        "fields": [
          { "label": "Auth Method", "value": "Universal Auth" },
          { "label": "Change", "value": "Added" },
          { "label": "Changed By", "value": "alice@example.com (user)" },
          { "label": "Changed At", "value": "September 10, 2026 at 10:00 AM UTC" }
        ]
      }
    ],
    "metadata": {
      "totalItems": 1,
      "viewUrl": "https://app.infisical.com/organizations/18b65352-ad1e-43d5-830f-65c72245c3a3/identities/c6002a8c-4571-4660-b169-f891f4734851"
    }
  }
}

When a signing secret is set, Infisical signs the request and sends it in the x-infisical-signature header:

x-infisical-signature: t=1786924804512,v1=9f8c1d...e3

t is a Unix timestamp in milliseconds, and v1 is HMAC-SHA256("<t>.<raw-request-body>", <signing-secret>) as a hex digest. Recompute it over the raw body rather than a re-serialized copy, then compare against v1 before trusting the payload and reject stale timestamps.

FAQ

Can I use machine identities with the CLI?

Yes - Identities can be used with the CLI.You can learn more about how to do this in the CLI quickstart here.

What is the difference between an identity and service token?

A service token is a project-level authentication method that is being deprecated in favor of identities. The service token method will be removed in a future release, so we recommend migrating any remaining service tokens to identities.Amongst many differences, identities provide broader access over the Infisical API, utilizes the same permission system as user identities, and come with a significantly larger number of configurable authentication and security features.If you’re looking for a simple authentication method, similar to service tokens, that can be bound onto an identity, we recommend checking out Token Auth.

Why can I not create, read, update, or delete an identity?

There are a few reasons for why this might happen:

You have insufficient organization permissions to create, read, update, delete identities.
The identity you’re trying to read, update, or delete is more privileged than yourself.
The role you’re trying to create an identity for or update an identity to is more privileged than yours.

Why didn't I get an alert for a credential expiring in a few hours?

Expiry alerts run once a day, so a credential whose entire lifetime is shorter than the gap between two runs can expire before an alert is ever due. Alerts are meant for credentials with TTLs measured in days.

What happens to an alert after I rotate the credential?

The new client secret is evaluated on its own TTL, and the old one drops out of the alert once it’s revoked or expires. No change to the alert is needed.

Does the auth method or credential change alert fire when I rotate a client secret?

Yes. Creating the new client secret sends one notification and revoking the old one sends another, each naming the secret by its description or prefix. Logging in with a client secret to mint an access token doesn’t fire it.

User identities