> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/SaaS/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/SaaS/govern/secure-your-data/intents/manage-intents.md).
# Manage Intents
Create, edit, or delete intents in the Immuta UI or using the API
{% hint style="info" %}
**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.
{% endhint %}
## Permissions
`GOVERNANCE` Immuta permission
## Create an intent
### With the UI
1. Click :users: **Identities** in the navigation menu and select **Intents**.
2. Click **New intent**.
3. Enter a **Name** and **Description** for the intent.
4. **Add attributes** to the intent. Start typing in the key and value fields to search for and select attribute key-value pairs. Once users [assume this intent](/SaaS/govern/secure-your-data/data-consumers/assume-an-intent.md), these attributes will replace existing attributes assigned to those users.
5. Select groups from the dropdown in the **Assign groups** section to assign group names to the intent. Users who are members of at least one of these groups will be able to [assume the intent](/SaaS/govern/secure-your-data/data-consumers/assume-an-intent.md).
6. Click **Create intent**.
### With the API
Copy the request example below and replace the values with your own as directed to create an intent.
{% code overflow="wrap" %}
```bash
curl -X 'POST' \
'https://www.organization.immuta.com/intent' \
-H "Authorization: Bearer " \
-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"] }
}'
```
{% endcode %}
1. Replace the **Immuta URL** and [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method) with your own.
2. Change the payload values to your own, where
* **name** is the name of the intent.
* **description** is an optional explanation of the intent.
* **groups.name** is the name of the group authorized to use the intent. Users who are members of at least one of these groups will be able to [assume the intent](/SaaS/govern/secure-your-data/data-consumers/assume-an-intent.md).
* **groups.iamid** is the unique identifier of the identity provider that contains the group. You can find this ID in the identity provider's configuration section on the app settings page or [through the Immuta API](/SaaS/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#search-all-iams). If you created the group in Immuta, this value is `bim`.
* **authorizations** is an object that includes an attribute key with an array of attribute values to assign to the intent. Once users [assume this intent](/SaaS/govern/secure-your-data/data-consumers/assume-an-intent.md), these attributes will replace existing attributes assigned to those users.
## Edit an existing intent
You can edit the name and description of an intent or change the attributes and groups of the intent.
Edit intent name and description
### With the UI
1. Click :users: **Identities** in the navigation menu and select **Intents**.
2. Click the :ellipsis-vertical: **overflow menu** icon on the intent you want to edit and select **Edit**.
3. Edit the **Name** and **Description** fields and click **Save**.
### With the API
Copy the request example below and replace the values with your own as directed to edit an intent.
{% code overflow="wrap" %}
```bash
curl -X 'PUT' \
'https://www.organization.immuta.com/intent/{id}' \
-H "Authorization: Bearer " \
-H 'Content-Type: application/json' \
-d '{
"name": "Fraud detection",
"description": "While acting under this intent, users can see internal data."
}'
```
{% endcode %}
1. Replace the **Immuta URL** and [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method) with your own.
2. Replace the **{id}** request parameter with the unique identifier of the intent you want to update. You can retrieve a list of intent IDs using the [`POST intent/search`](/SaaS/developer-guides/api-intro/immuta-v1-api/manage-data-access/manage-intents.md#post-intent-search) endpoint.
3. Change the payload values to your own, where
* **name** is the name of the intent.
* **description** is an optional explanation of the intent.
Edit attributes
### Add attributes
#### With the UI
1. Click :users: **Identities** in the navigation menu and select **Intents**.
2. Click the intent name on the **Intents** page to open the side sheet and select the **Attributes** tab.
3. To add attributes, click **Add attributes** and start typing in the key and value fields to search for and select attribute key-value pairs.
4. Click **Save changes**.
#### With the API
Copy the request example below and replace the values with your own as directed to add attributes to an intent.
{% code overflow="wrap" %}
```bash
curl -X 'PATCH' \
'https://www.organization.immuta.com/intent/{id}/attributes/add' \
-H "Authorization: Bearer " \
-H 'Content-Type: application/json' \
-d '{
"authorizations": { "ClearanceLevel" :["High"] }
}'
```
{% endcode %}
1. Replace the **Immuta URL** and [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method) with your own.
2. Replace the **{id}** request parameter with the unique identifier of the intent you want to update. You can retrieve a list of intent IDs using the [`POST intent/search`](/SaaS/developer-guides/api-intro/immuta-v1-api/manage-data-access/manage-intents.md#post-intent-search) endpoint.
3. Change the payload values to your own, where **authorizations** is an object that includes attribute keys with arrays of attribute values to assign to the intent.
### Remove attributes
#### With the UI
1. Click :users: **Identities** in the navigation menu and select **Intents**.
2. Click the intent name on the **Intents** tab to open the side sheet and select the **Attributes** tab.
3. Click the :ellipsis-vertical: **overflow menu** icon on the attribute you want to remove and select **Edit**.
4. Click the **X** icon on the attribute keys or values that you want to remove.
5. Click **Save changes**.
#### With the API
Copy the request example below and replace the values with your own as directed to remove attributes from an intent.
{% code overflow="wrap" %}
```bash
curl -X 'PATCH' \
'https://www.organization.immuta.com/intent/{id}/attributes/remove' \
-H "Authorization: Bearer " \
-H 'Content-Type: application/json' \
-d '{
"authorizations": { "ClearanceLevel" :["High"] }
}'
```
{% endcode %}
1. Replace the **Immuta URL** and [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method) with your own.
2. Replace the **{id}** request parameter with the unique identifier of the intent you want to update. You can retrieve a list of intent IDs using the [`POST intent/search`](/SaaS/developer-guides/api-intro/immuta-v1-api/manage-data-access/manage-intents.md#post-intent-search) endpoint.
3. Change the payload values to your own, where **authorizations** is an object that includes attribute keys with arrays of attribute values to remove from the intent.
Edit groups
### Add groups
#### With the UI
1. Click :users: **Identities** in the navigation menu and select **Intents**.
2. Click the intent name on the **Intents** page to open the side sheet and select the **Assigned** **groups** tab.
3. Click **Assign groups** and select groups from the dropdown menu.
4. Click **Add to groups**.
#### With the API
Copy the request example below and replace the values with your own as directed to add groups to an intent.
{% code overflow="wrap" %}
```bash
curl -X 'POST' \
'https://www.organization.immuta.com/intent/{id}/groupAssignment' \
-H "Authorization: Bearer " \
-H 'Content-Type: application/json' \
-d '{
"groups": [ {"name": "Research", "iamid": "bim"} ]
}'
```
{% endcode %}
1. Replace the **Immuta URL** and [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method) with your own.
2. Replace the **{id}** request parameter with the unique identifier of the intent you want to update. You can retrieve a list of intent IDs using the [`POST intent/search`](/SaaS/developer-guides/api-intro/immuta-v1-api/manage-data-access/manage-intents.md#post-intent-search) endpoint.
3. Change the payload values to your own, where
* **groups.name** is the name of the group authorized to use the intent.
* **groups.iamid** is the unique identifier of the identity provider that contains the group. You can find this ID in the identity provider's configuration section on the app settings page or [through the Immuta API](/SaaS/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#search-all-iams). If you created the group in Immuta, this value is `bim`.
### Remove groups
#### With the UI
1. Click :users: **Identities** in the navigation menu and select **Intents**.
2. Click the intent name on the **Intents** page to open the side sheet and select the **Assigned** **groups** tab.
3. Click the :ellipsis-vertical: **overflow menu** icon on the group you want to remove and select **Remove**.
4. Click **Remove** again to confirm your changes.
#### With the API
Copy the request example below and replace the values with your own as directed to remove groups from an intent.
{% code overflow="wrap" %}
```bash
curl -X 'DELETE' \
'https://www.organization.immuta.com/intent/{id}/groupAssignment' \
-H "Authorization: Bearer " \
-H 'Content-Type: application/json' \
-d '{
"groups": [ {"name": "Research", "iamid": "bim"} ]
}'
```
{% endcode %}
1. Replace the **Immuta URL** and [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method) with your own.
2. Replace the **{id}** request parameter with the unique identifier of the intent you want to update. You can retrieve a list of intent IDs using the [`POST intent/search`](/SaaS/developer-guides/api-intro/immuta-v1-api/manage-data-access/manage-intents.md#post-intent-search) endpoint.
3. Change the payload values to your own, where
* **groups.name** is the name of the group to remove from the intent.
* **groups.iamid** is the unique identifier of the identity provider that contains the group. You can find this ID in the identity provider's configuration section on the app settings page or [through the Immuta API](/SaaS/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md#search-all-iams). If you created the group in Immuta, this value is `bim`.
## Delete an intent
### With the UI
1. Click :users: **Identities** in the navigation menu and select **Intents**.
2. Click the :ellipsis-vertical: **overflow menu** icon on the intent you want to delete and select **Delete**.
3. Click **Confirm**.
### With the API
Copy the request example below and replace the values with your own as directed to delete an intent.
{% code overflow="wrap" %}
```bash
curl -X 'DELETE' \
'https://www.organization.immuta.com/intent/{id}' \
-H "Authorization: Bearer " \
-H 'Content-Type: application/json'
```
{% endcode %}
1. Replace the **Immuta URL** and [**bearer token**](/SaaS/developer-guides/api-intro/authentication.md#bearer-token-method) with your own.
2. Replace the **{id}** request parameter with the unique identifier of the intent you want to delete. You can retrieve a list of intent IDs using the [`POST intent/search`](/SaaS/developer-guides/api-intro/immuta-v1-api/manage-data-access/manage-intents.md#post-intent-search) endpoint.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://documentation.immuta.com/SaaS/govern/secure-your-data/intents/manage-intents.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.