Machine identities

A machine identity lets an application, script, or other workload use Infisical without a user account. A machine identity works like an IAM user in AWS or a service account in Google Cloud. Each machine identity has a role that controls what the identity can access, and one or more auth methods. Your workload logs in with an auth method, gets a short-lived access token, and sends the token with each request to the Infisical API. Organization Identities

Organization and project identities

You can create a machine identity either in an organization or in a project. Both work the same way, except for where you manage them and what they can access:

	Project identity	Organization identity
Managed in	The project	The organization
Can access	Only its own project	Each project you add the identity to, and organization-level actions
Use it when	Each team manages its own project	A workload works across several projects

Set up a machine identity

Project identity
Organization identity

In your project, go to Access Control > Machine Identities and create an identity with a name and a role. You can pick a role that Infisical includes, such as Viewer for read-only access, or a custom role.

Set up the auth method that matches where your workload runs, such as AWS Auth for a workload on AWS.

Infisical adds Universal Auth to each new identity. To log in with Universal Auth, create a client secret. If you use a different auth method, you can remove Universal Auth from the identity.

From your workload, log in with the auth method to get a short-lived access token.

Send the access token with each request to the Infisical API.

Authentication methods

A machine identity logs in to Infisical with an auth method. Pick the auth method that matches where your workload runs:

Identity lockout

Lockout protects Universal Auth and LDAP Auth from brute-force attacks. By default, after 3 consecutive failed login attempts within 30 seconds, Infisical blocks logins with that auth method on the identity for 5 minutes. To change these limits or turn lockout off, edit the auth method on the identity.

Revoke access tokens

An access token expires after the Access Token TTL set on the auth method, which is 30 days by default. You can revoke the token before it expires. Infisical revokes an access token when you:

Revoke the token through the API, such as with Revoke access token for Universal Auth or Revoke token for Token Auth
Delete the identity, which revokes all of its access tokens
Remove the credential that Infisical issued the token for, such as a Universal Auth client secret, or remove the auth method from the identity

After Infisical revokes a token, it rejects requests that use the token, and the token can’t be renewed.

If Infisical’s cache (Redis) is briefly unavailable when you revoke a token, Infisical can keep accepting that token for up to 12 minutes. To make sure a token stops working right away, delete the credential that Infisical issued the token for, such as the Universal Auth client secret, or delete the identity.

Alerts

An alert on a machine identity sends a notification to your team through the channels you choose. Each alert watches one of these events:

Event	When the alert fires
Credential Expiration	A set number of days before a Universal Auth client secret or Token Auth access token expires (Infisical checks once a day)
Auth Method Change	As soon as someone adds, updates, or removes an auth method, or creates, updates, or revokes a Universal Auth client secret or Token Auth token

Credential expiration

This alert notifies your team before a credential on the identity expires, so you can replace the credential before your workload loses access to Infisical. The alert skips revoked credentials, and checks each credential type against a different expiry date:

Credential	Expiry date the alert checks
Universal Auth client secret	The time the secret was created plus its TTL. If the TTL is `0` (the default), the secret never expires, and the alert ignores it.
Token Auth access token	The time the token was created plus its access token TTL. If the TTL is `0`, the alert ignores the token.

If you renew a Token Auth token, the alert still checks the token’s original expiry date, and doesn’t fire again after that date passes. Removing the alert and creating it again doesn’t change the date. To get alerts for a later expiry date, create a new token.

For Universal Auth, the alert checks the client secret, not the access tokens that an identity gets by logging in with the secret. Those access tokens are short-lived and renewed by your application. See Universal Auth for the difference between Client Secret TTL, Access Token TTL, and Access Token Max TTL.

Auth method change

This alert tells your team when someone changes how the identity can log in. The alert fires each time:

Someone adds, updates, or removes an auth method on the identity
Someone creates or revokes a Universal Auth client secret
Someone creates, renames, or revokes a Token Auth token

Logging in doesn’t count as a change, so the alert doesn’t fire each time your workload gets an access token.

Each notification names the auth method, the kind of change, the credential if one changed, who made the change (a user’s email or a machine identity’s name), and when the change happened.

Create an alert

An identity can have one alert for each event.

Open the machine identity and select Alerts at the top right of the page. If the identity already has alerts, select Add Alert at the bottom of the list.

Fill in the alert’s fields. Create Machine Identity Alert

Field	Description
Name	A name for the alert, such as `ua-secret-expiry`
Description	Optional notes about what the alert is for
Event	Credential Expiration or Auth Method Change (you can’t change the event later)
Enabled	Whether Infisical sends notifications for the alert (on by default)
Condition	For Credential Expiration only: how many days before a credential expires to send the notification, from `1` to `90`
Repeat daily until the secret is rotated	For Credential Expiration only: if selected, Infisical sends the notification every day until the credential expires or is replaced, instead of once

Select Add channel and set up at least one notification channel.

Select Create Alert.

Manage alerts

Select Alerts on the machine identity to see its alerts. Use the toggle next to an alert to turn it on or off, or open the menu next to the toggle and select Edit or Remove.

Notification channels

Each alert sends notifications to between 1 and 10 channels:

Channel	Configuration
Email	Users and groups in your organization, up to 20 per channel. If someone joins a group after you add the group, they also get the notifications.
Slack	An Incoming Webhook URL that uses HTTPS and has the exact hostname `hooks.slack.com`
PagerDuty	An Events API v2 integration key (a 32-character hex string). Infisical opens one incident per expiring credential, and adds repeated changes of the same kind to the same auth method to one open incident.
Webhook	An HTTPS URL, with an optional signing secret, authentication (bearer token, basic auth, or API key), and custom headers. If you change the URL, enter the credentials again, because Infisical only sends them to the URL they were saved with.

Webhook payload

Infisical sends each webhook as a CloudEvents 1.0 JSON document. The value of the type field depends on the event that fired the alert:

com.infisical.identity.authentication.expiration for credential expiration
com.infisical.identity.authentication.auth-method-changed for an auth method change

For credential expiration, data.items lists each credential that the daily check found:

{
  "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" }
        ]
      },
      {
        "id": "token-auth-token:9d4b2e7a-3c1f-4a8e-b5d6-2f7c8e9a1b3d",
        "title": "release-runner",
        "fields": [
          { "label": "Secret Name", "value": "release-token" },
          { "label": "Secret Type", "value": "Token Auth Access Token" },
          { "label": "Expires", "value": "August 21, 2026 at 09:00 AM UTC" }
        ]
      }
    ],
    "metadata": {
      "totalItems": 2,
      "viewUrl": "https://app.infisical.com/organizations/18b65352-ad1e-43d5-830f-65c72245c3a3/identities/c6002a8c-4571-4660-b169-f891f4734851"
    }
  }
}

For an auth method change, data.items has one item. Its 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": "[email protected] (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"
    }
  }
}

Verify webhook signatures

If you set a signing secret on a webhook channel, Infisical signs each request and sends the signature in the x-infisical-signature header:

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

t is the time Infisical sent the request, as a Unix timestamp in milliseconds
v1 is HMAC-SHA256("<t>.<raw-request-body>", <signing-secret>), as a hex string

To verify a request before you trust its payload:

Compute the HMAC over the raw request body, not over a copy you parsed and serialized again.

Compare the result with v1.

Reject the request if t is older than you allow, such as five minutes.

FAQ

Can I use machine identities with the CLI?

Yes. To log in to the CLI as a machine identity, see CLI usage.

What's the difference between a machine identity and a service token?

Service tokens are deprecated and will be removed in a future release, so migrate any service tokens you still use to machine identities.Compared with a service token, a machine identity:

Can call more of the Infisical API
Uses the same permission system as users
Supports more auth methods and security settings, such as lockout

If you want a single token that works like a service token, add Token Auth to a machine identity.

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

Infisical blocks the action if:

Your organization role doesn’t have permission to manage identities
The identity you’re reading, updating, or deleting has more privileges than you
The role you’re giving the identity has more privileges than your role

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

Infisical checks for expiring credentials once a day, so a credential that lasts less than a day can expire before a check finds it. Use expiration alerts for credentials with TTLs of several days or more.

What happens to an alert after I rotate the credential?

Nothing changes on the alert. The alert checks the new client secret against the new secret’s TTL, and stops checking the old secret once you revoke it or it expires.

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

Yes. Infisical sends one notification when you create the new client secret and another when you revoke the old one. Each notification names the secret by its description or prefix.

User identities