Manage Intents

Intents API reference guide

Public preview: This feature is being released incrementally to customers on a rolling basis. If the feature is not available in your tenant yet, contact your Immuta representative to enable it.

The intent API allows users to create and manage intents.

Permissions

GOVERNANCE Immuta permission

Endpoints and methods

Method	Endpoint	Description
POST	/intent	Creates a new intent
DELETE	/intent/{id}	Deletes an intent
GET	/intent/{id}	Retrieves an intent
PUT	/intent/{id}	Updates an intent name or description
PUT, POST	/intent/{id}/attributes	Updates attributes assigned to the intent
PATCH	/intent/{id}/attributes/{action}	Adds or removes attributes from an intent
DELETE	/intent/{id}/groupAssignment	Removes groups from the intent
POST	/intent/{id}/groupAssignment	Assigns groups to the intent
POST	/intent/search	Retrieves a list of intents

POST /intent

Create a new intent. You can also add a description, assign or remove groups, and assign or remove attributes after creating the intent.

curl -X 'POST' \
    'https://www.organization.immuta.com/intent' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "name": "Fraud detection",
    "description": "While acting under this intent, users can see internal data.",
    "groups": [ {"name": "Analysts", "iamid": "bim"} ],
    "authorizations": { "Exception": ["Internal"] }
    }'

Body parameters

Parameter	Description	Required or optional	Accepted values
name string	The name of the intent.	Required	-
description string	The description of the intent that will be displayed for users.	Optional	-
authorizations object	The attribute key-value pairs assigned to the intent.	Required	-
groups.name string	The group names assigned to the intent.	Required	-
groups.iamid string	The unique identifier of the identity provider that contains the groups. You can find this ID in the identity provider's configuration section on the app settings page or through the Immuta API. If you created the group in Immuta, this value is bim.	Required	-

Response

Returns the intent object.

{
  "id": 1,
  "name": "Fraud detection",
  "description": "While acting under this intent, users can see internal data.",
  "authorizations": {
    "Exception": [
      "Internal"
    ]
  },
  "deleted": false,
  "createdAt": "2026-05-04T18:48:40.602Z",
  "updatedAt": "2026-05-04T19:38:52.438Z",
  "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}

DELETE /intent/{id}

Delete an intent.

curl -X 'DELETE' \
    'https://www.organization.immuta.com/intent/{id}' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json'

Path parameter

Parameter	Description
id integer	The unique identifier of the intent. You can retrieve a list of intent IDs using the /intent/search endpoint.

Response

Returns a 200 code when the intent is successfully deleted.

GET /intent/{id}

Retrieve a specific intent.

curl -X 'GET' \
    'https://www.organization.immuta.com/intent/{id}' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json'

Path parameter

Parameter	Description
id integer	The unique identifier of the intent. You can retrieve a list of intent IDs using the /intent/search endpoint.

Response

Returns the intent object.

{
  "id": 1,
  "name": "Fraud detection",
  "description": "While acting under this intent, users can see internal data.",
  "authorizations": {
    "Exception": [
      "Internal"
    ]
  },
  "deleted": false,
  "createdAt": "2026-05-04T18:48:40.602Z",
  "updatedAt": "2026-05-04T19:38:52.438Z",
  "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}

PUT /intent/{id}

Update the intent name or description.

curl -X 'PUT' \
    'https://www.organization.immuta.com/intent/{id}' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "name": "Fraud detection",
    "description": "This intent allows users in the Analysts group to see internal data."
    }'

Path parameter

Parameter	Description
id integer	The unique identifier of the intent. You can retrieve a list of intent IDs using the /intent/search endpoint.

Body parameters

Parameter	Description
name string	The name of the intent.
description string	The description of the intent.

Response

Returns the intent object.

{
  "id": 1,
  "name": "Fraud detection",
  "description": "This intent allows users in the Analysts group to see internal data.",
  "authorizations": {
    "Exception": [
      "Internal"
    ]
  },
  "deleted": false,
  "createdAt": "2026-05-04T18:48:40.602Z",
  "updatedAt": "2026-05-04T19:38:52.438Z",
  "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}

PUT, POST /intent/{id}/attributes

Update the attributes assigned to the intent. The attributes included in the payload will replace existing attributes assigned to the intent.

curl -X 'PUT' \
    'https://www.organization.immuta.com/intent/{id}/attributes' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "authorizations": { "ClearanceLevel" :["High"] }
    }'

Path parameter

Parameter	Description
id integer	The unique identifier of the intent. You can retrieve a list of intent IDs using the /intent/search endpoint.

Body parameter

Parameter	Description
authorizations object	Includes attribute keys that each pair with an array of attribute values.

Response

Returns the intent object.

{
  "id": 1,
  "name": "Fraud detection",
  "description": "This intent allows users in the Analysts group to see internal data.",
  "authorizations": {
    "ClearanceLevel": [
      "High"
    ]
  },
  "deleted": false,
  "createdAt": "2026-05-04T18:48:40.602Z",
  "updatedAt": "2026-05-04T19:38:52.438Z",
  "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}

PATCH /intent/{id}/attributes/{action}

Add or remove specific attributes from an intent.

curl -X 'PATCH' \
    'https://www.organization.immuta.com/intent/{id}/attributes/remove' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "authorizations": { "ClearanceLevel" :["High"] }
    }'

Path parameters

Parameter	Description
id integer	The unique identifier of the intent. You can retrieve a list of intent IDs using the /intent/search endpoint.
action string	Specifies whether to add or remove the provided attribute.

Body parameter

Parameter	Description
authorizations object	Includes attribute keys that each pair with an array of attribute values.

Response

Returns the intent object.

{
    "id": 1,
    "name": "Fraud detection",
    "description": "This intent allows users in the Analysts group to see internal data.",
    "authorizations": {},
    "deleted": false,
    "createdAt": "2026-05-04T18:48:40.602Z",
    "updatedAt": "2026-05-07T14:43:17.414Z",
    "groups": [
    {
      "name": "Analysts",
      "iamid": "bim"
    }
  ]
}

DELETE /intent/{id}/groupAssignment

Remove groups from the intent.

curl -X 'DELETE' \
    'https://www.organization.immuta.com/intent/{id}/groupAssignment' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "groups": [ {"name": "Analysts", "iamid": "bim"} ]
    }'

Path parameter

Parameter	Description
id integer	The unique identifier of the intent. You can retrieve a list of intent IDs using the /intent/search endpoint.

Body parameters

Parameter	Description
groups.name string	The group names assigned to the intent.
groups.iamid string	The unique identifier of the identity provider that contains the groups. You can find this ID in the identity provider's configuration section on the app settings page or through the Immuta API. If you created the group in Immuta, this value is bim.

Response

Returns group objects that were removed from the intent.

{
    "unassignedGroups": [
        {
            "name": "Analysts",
            "iamid": "bim",
            "id": 7
        }
    ],
    "errors": []
}

Response schema

Attribute	Description
unassignedGroups array	An array of group objects that were removed from the intent.
name string	The name of the group removed from the intent.
iamid string	The unique identifier of the identity provider that contains the group that was removed from the intent.
id integer	The unique identifier of the group in Immuta.
errors array	An array of errors resulting from attempted group assignments. For example, Group with name Engineers and iamid bim does not exist.

POST /intent/{id}/groupAssignment

Assign groups to an intent.

curl -X 'POST' \
    'https://www.organization.immuta.com/intent/{id}/groupAssignment' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "groups": [ {"name": "Research", "iamid": "bim"} ]
    }'

Path parameter

Parameter	Description
id integer	The unique identifier of the intent. You can retrieve a list of intent IDs using the /intent/search endpoint.

Body parameters

Parameter	Description
groups.name string	The group names to assign to the intent.
groups.iamid string	The unique identifier of the identity provider that contains the groups. You can find this ID in the identity provider's configuration section on the app settings page or through the Immuta API. If you created the group in Immuta, this value is bim.

Response

Returns a list of groups assigned to the intent.

{
    "groups": [
        {
            "name": "Research",
            "iamid": "bim",
            "id": 7
        }
    ],
    "errors": []
}

Response schema

Attribute	Description
groups array	An array of group objects that were assigned to the intent.
name string	The name of the group assigned to the intent.
iamid string	The unique identifier of the identity provider that contains the group that was assigned to the intent.
id integer	The unique identifier of the group in Immuta.
errors array	An array of errors resulting from attempted group assignments. For example, Group with name Engineers and iamid bim does not exist.

POST /intent/search

Search for intents.

curl -X 'POST' \
    'https://www.organization.immuta.com/intent/search' \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -H 'Content-Type: application/json' \
    -d '{
    "searchText": "Fraud",
    "limit": 2
    }'

Body parameters

Parameter	Description	Required or optional	Accepted values
attributes object	Returns intents that contain this attribute.	Optional	-
groups string	Returns intents that contain this group.	Optional	-
limit integer	The number of intents to return.	Optional	Minimum value is 1. Maximum value is 100.
offset integer	The number of items from the beginning of the response to exclude. You can combine the offset and limit parameters to return a specific set of intents. For example, to return the second and third intent in the response, you would set offset=1 and limit=2.	Optional	Minimum value is 0. Maximum value is the total number of intents minus limit.
searchText string	The text to search for in intent names. This will return intents with a name that contains this search text.	Optional	-
sortField string	Specifies the field to sort the results by.	Optional	createdAt id name updatedAt
sortOrder string	Specifies how to sort the results of the request.	Optional	asc desc

Response

Returns a list of intent objects that match the search criteria.

{
  "intents": [
    {
      "id": 1,
      "name": "Fraud detection",
      "createdAt": "2026-05-04T18:48:40.602Z",
      "updatedAt": "2026-05-07T14:18:01.026Z",
      "groupCount": 1,
      "attributeCount": 1
    }
  ],
  "total": 1
}

Response schema

Attribute	Description
intents.id integer	The unique identifier of the intent.
intents.name string	The name of the intent.
intents.attributeCount integer	The total number of attribute key-value pairs assigned to the intent.
intents.groupCount integer	The total number of groups assigned to the intent.
intents.createdAt timestamp	The date and time the intent was created.
intents.updatedAt timestamp	The date and time the intent was updated.
total integer	The total number of intents that match the search criteria.

Intent object attributes

Attribute	Description
id integer	The unique identifier of the intent.
name string	The name of the intent.
description string	The description of the intent that will be displayed for users.
authorizations object	The attribute key-value pairs assigned to the intent.
groups.name string	The group names assigned to the intent.
groups.iamid string	The unique identifier of the identity provider that contains the groups.
createdAt timestamp	The date and time the intent was created.
updatedAt timestamp	The date and time the intent was updated.
deleted boolean	Indicates whether the intent has been deleted.
errors array	An array of errors resulting from attempted group assignments. For example, Group with name Engineers and iamid bim does not exist.