> ## 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.

# Machine identities

> Give applications and other workloads access to Infisical without a user account.

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](https://infisical.com/docs/documentation/platform/access-controls/role-based-access-controls.md) that controls what the identity can access, and one or more [auth methods](#authentication-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](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/organization/organization-machine-identities.png)

## 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

> [tab] Project identity
>
> **Step 1**
>
> In your project, go to **Access Control** > **Machine Identities** and create an identity with a name and a [role](https://infisical.com/docs/documentation/platform/access-controls/role-based-access-controls.md). You can pick a role that Infisical includes, such as **Viewer** for read-only access, or a custom role.
>
> **Step 2**
>
> Set up the [auth method](#authentication-methods) that matches where your workload runs, such as AWS Auth for a workload on AWS.
>
> > [!NOTE]
> >
> > Infisical adds [Universal Auth](https://infisical.com/docs/documentation/platform/identities/universal-auth.md#guide) 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.
>
> **Step 3**
>
> From your workload, log in with the auth method to get a short-lived access token.
>
> **Step 4**
>
> Send the access token with each request to the Infisical API.

> [tab] Organization identity
>
> **Step 1**
>
> In your organization, go to **Access Control** > **Machine Identities** and create an identity with a name and a [role](https://infisical.com/docs/documentation/platform/access-controls/role-based-access-controls.md). You can pick a role that Infisical includes, such as **Member**, or a custom role.
>
> **Step 2**
>
> Set up the [auth method](#authentication-methods) that matches where your workload runs, such as AWS Auth for a workload on AWS.
>
> > [!NOTE]
> >
> > Infisical adds [Universal Auth](https://infisical.com/docs/documentation/platform/identities/universal-auth.md#guide) 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.
>
> **Step 3**
>
> Add the identity to each project it needs to access.
>
> **Step 4**
>
> From your workload, log in with the auth method to get a short-lived access token.
>
> **Step 5**
>
> 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:

Search authentication methods

Filter authentication methods

found

## Identity lockout

Lockout protects [Universal Auth](https://infisical.com/docs/documentation/platform/identities/universal-auth.md) and [LDAP Auth](https://infisical.com/docs/documentation/platform/identities/ldap-auth/general.md) 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](https://infisical.com/docs/api-reference/endpoints/universal-auth/revoke-access-token.md) for Universal Auth or [Revoke token](https://infisical.com/docs/api-reference/endpoints/token-auth/revoke-token.md) 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.

> [!NOTE]
>
> 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](#notification-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.

> [!NOTE]
>
> 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](https://infisical.com/docs/documentation/platform/identities/universal-auth.md) 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

> [!NOTE]
>
> 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.

**Step 1**

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.

**Step 2**

Fill in the alert's fields.

![Create Machine Identity Alert](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/organization/mi-create-alert.png)

| 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 |

**Step 3**

Select **Add channel** and set up at least one [notification channel](#notification-channels).

**Step 4**

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](https://api.slack.com/messaging/webhooks) URL that uses HTTPS and has the exact hostname `hooks.slack.com` |
| **PagerDuty** | An [Events API v2](https://developer.pagerduty.com/docs/events-api-v2-overview) 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](#verify-webhook-signatures), 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](https://cloudevents.io/) 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:

```json expandable theme={"dark"}
{
  "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`:

```json expandable theme={"dark"}
{
  "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"
    }
  }
}
```

### 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:

**Step 1**

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

**Step 2**

Compare the result with `v1`.

**Step 3**

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

## FAQ

> [accordion] Can I use machine identities with the CLI?
>
> Yes. To log in to the CLI as a machine identity, see [CLI usage](https://infisical.com/docs/cli/usage.md).

> [accordion] What's the difference between a machine identity and a service token?
>
> [Service tokens](https://infisical.com/docs/documentation/platform/token.md) 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](#identity-lockout)
>
> If you want a single token that works like a service token, add [Token Auth](https://infisical.com/docs/documentation/platform/identities/token-auth.md) to a machine identity.

> [accordion] 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

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.