Manage Frameworks

Frameworks API reference guide

The frameworks resource allows you to create and manage classification frameworks. System-created frameworks cannot be edited, so create a clone to make any adjustments.

Endpoints

Method	Endpoint	Description
GET	/frameworks	Gets all the frameworks
POST	/frameworks	Creates a new framework
DELETE	/frameworks/{frameworkId}	Deletes a framework
GET	/frameworks/{frameworkId}	Gets the framework with the given framework ID
PUT	/frameworks/{frameworkId}	Updates a framework
POST	/frameworks/{frameworkId}/clone	Clones a framework
GET	/frameworks/{frameworkId}/versions	Gets all versions of the framework with the given framework ID

GET /frameworks

Get all the frameworks in Immuta.

curl -X 'GET' \
    'https://www.organization.immuta.com/frameworks' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

Response

The response returns all the frameworks in Immuta. See the framework reference section for details about the response schema.

POST /frameworks

Create a new framework. This example creates a framework that will tag all columns in a data source with the tag "HR Framework . Internal Employee Data" when a single column within the data source has the tag "Employee Name". Then subscription and data policies can be built to only allow HR to access this sensitive employee data.

Rule limit

Frameworks can have a maximum of 50 rules.

curl -X 'POST' \
    'https://www.organization.immuta.com/frameworks' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "active": true,
    "shortName": "HR Information",
    "name": "HR Information Framework",
    "description": "This framework finds internal employee information and tags it for HR.",
    "tags": [
    {
      "name": "HR Framework.Internal Employee Data",
      "source": "curated",
      "sensitivities": []
    }],
    "rules": [
    { "name": "HR Rule 1",
      "classificationTag": {
        "name": "HR Framework.Internal Employee Data",
        "source": "curated"
      },
      "columnTags": [],
      "neighborColumnTags": [
        {
        "name": "Employee Name",
        "source": "curated"
        }
      ],
      "tableTags": []
      }
    ]}'

Body parameters

The request accepts a JSON or YAML payload. See the framework payload description for parameter details.

Response

The response returns the framework that was created. See the framework reference section for details about the response schema.

{
  "id": "9a6bf3b1-823c-4b2e-aef9-570dac6793cc",
  "version": "4e823e0b-8e38-455d-b23c-1f03200d203a",
  "shortName": "HR Information",
  "name": "HR Information Framework",
  "description": "This framework finds internal employee information and tags it for HR.",
  "createdBy": 2,
  "createdAt": "2023-10-19T16:14:39.109Z",
  "tags": [
    {
      "name": "HR Framework.Internal Employee Data",
      "source": "curated",
      "sensitivities": []
    }
  ],
  "rules": [
    {  "name": "HR Rule 1",
      "classificationTag": {
        "name": "HR Framework.Internal Employee Data",
        "source": "curated"
      },
      "columnTags": [],
      "neighborColumnTags": [
        {
          "name": "Employee Name",
          "source": "curated"
        }
      ],
      "tableTags": []
    }
  ],
  "active": true
}

DELETE /frameworks/{frameworkId}

Deletes the framework you specify in the request.

curl -X 'DELETE' \
    'https://www.organization.immuta.com/frameworks/123456' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

Request parameter

Parameter	Description	Required or optional
id number	The unique identifier of the framework.	Required

Response

The response returns a 204 response code if the request was successful.

GET /frameworks/{frameworkId}

Gets the framework you specify in the request.

curl -X 'GET' \
    'https://www.organization.immuta.com/frameworks/123456' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

Request parameter

Parameter	Description	Required or optional
id number	The unique identifier of the framework.	Required

Response

The response returns the framework specified in the request. See the framework reference section for details about the response schema.

PUT /frameworks/{frameworkId}

Update a framework. This example updates a framework to be inactive.

curl -X 'PUT' \
    'https://www.organization.immuta.com/frameworks/123456' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "active": false
    }'

Request parameter

Parameter	Description	Required or optional
id number	The unique identifier of the framework.	Required

Body parameters

The request accepts a JSON or YAML payload. See the framework payload description for parameter options; partial updates are supported.

Response

The response returns the framework that was updated. See the framework reference section for details about the response schema.

{
  "id": "123456",
  "version": "4e823e0b-8e38-455d-b23c-1f03200d203a",
  "shortName": "HR Information",
  "name": "HR Information Framework",
  "description": "This framework finds internal employee information and tags it for HR.",
  "createdBy": 2,
  "createdAt": "2023-10-19T16:14:39.109Z",
  "tags": [
    {
      "name": "HR Framework.Internal Employee Data",
      "source": "curated",
      "sensitivities": []
    }
  ],
  "rules": [
    { "name": "HR Rule 1",
      "classificationTag": {
        "name": "HR Framework.Internal Employee Data",
        "source": "curated"
      },
      "columnTags": [],
      "neighborColumnTags": [
        {
          "name": "Employee Name",
          "source": "curated"
        }
      ],
      "tableTags": []
    }
  ],
  "active": false
}

POST /frameworks/{frameworkId}/clone

Clone a framework from an existing framework.

curl -X 'POST' \
    'https://www.organization.immuta.com/frameworks/123456/clone' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

Request parameter

Parameter	Description	Required or optional
id number	The unique identifier of the framework.	Required

Response

The response returns the framework that was created as a clone. See the framework reference section for details about the response schema.

{
  "id": "123456",
  "version": "4e823e0b-8e38-455d-b23c-1f03200d203a",
  "shortName": "HR Information",
  "name": "HR Information Framework",
  "description": "This framework finds internal employee information and tags it for HR.",
  "createdBy": 2,
  "createdAt": "2023-10-19T16:14:39.109Z",
  "tags": [
    {
      "name": "HR Framework.Internal Employee Data",
      "source": "curated",
      "sensitivities": []
    }
  ],
  "rules": [
    { "name": "HR Rule 1",
      "classificationTag": {
        "name": "HR Framework.Internal Employee Data",
        "source": "curated"
      },
      "columnTags": [],
      "neighborColumnTags": [
        {
          "name": "Employee Name",
          "source": "curated"
        }
      ],
      "tableTags": []
    }
  ],
  "active": false
}

GET /frameworks/{frameworkId}/versions

Gets every version of the framework you specify in the request.

curl -X 'GET' \
    'https://www.organization.immuta.com/frameworks/123456/versions' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

Request parameter

Parameter	Description	Required or optional
id number	The unique identifier of the framework.	Required

Response

The response returns a copy of every version of the framework specified in the request. See the framework reference section for details about the response schema.

Framework payload

The framework payload is used when creating or updating a framework. See the parameters below.

Parameter	Description	Required or optional	Default values	Accepted values
shortName string	The short, human-readable name for the framework.	Required	-	-
name string	The official, human-readable name for the framework.	Required	-	-
description string	A description of the framework.	Required	-	-
tags array[]	The tags used in the framework and the sensitivity attached to them. Each tag used must have a tags object. See the tags object description for child parameters.	Required	-	-
rules array[]	The rules used to apply the tags in the framework. See the rules object description for child parameters.	Required	-	-
active boolean	When true, the framework will be actively used on data sources in Immuta.	Required	-	true false

Tags object

The tags object specifies the tags created for and used in the framework. It includes metadata for the tags, like sensitivity and descriptions. The table below outlines its child parameters.

Parameter	Description	Required or optional	Default values	Accepted values
name string	The fully rendered name of the tag, including any parent tags.	Required	-	-
source string	The catalog the tag is from. curated is any tag in Immuta.	Required	-	curated The external catalog ID
description string	A description of the classification tag.	Required	-	-
sensitivities object	The sensitivity assigned to the tag. This sensitivity can drive the audit dashboards and monitors.	Optional	[]	-
sensitivities.dimension string	The type of sensitivity assigned to the tag.	Required if adding sensitivities	-	confidentiality
sensitivities.sensitivity integer	The sensitivity assigned to the tag.	Required if adding sensitivities	-	0 - This tag signifies non-sensitive data. 1 - This tag signifies sensitive data. 2 - This tag signifies highly-sensitive data.

Rules object

The rules object specifies the rules used in the framework. The table below outlines its child parameters.

Parameter	Description	Required or optional	Default values	Accepted values
name string	The short, human-readable name for the rule.	Required	-	-
classificationTag object	The tag to apply to the data source based on the criteria.	Required	-	-
classificationTag.name string	The name of the tag to apply.	Required	-	-
classificationTag.source string	The catalog the tag is from. curated is any tag in Immuta.	Required	-	curated The external catalog ID
columnTags object	The criteria for applying tags. Tags will be applied to a column when these tags are found on the same column.	Optional	[]	-
columnTags.name string	The name of the column tag. When matched, the classification tag will be applied to the same column.	Required if using columnTags criteria	-	-
columnTags.source string	The catalog the column tag is from. curated is any tag in Immuta.	Required if using columnTags criteria	-	curated The external catalog ID
neighborColumnTags object	The criteria for applying tags. Tags will be applied to all columns within a data source if this tag is found already applied to any column within the data source.	Optional	[]	-
neighborColumnTags.name string	The name of the neighboring column tag. When matched, the classification tag will be applied to all columns within that data source.	Required if using neighborColumnTags criteria	-	-
neighborColumnTags.source string	The catalog the neighboring column tag is from. curated is any tag in Immuta.	Required if using neighborColumnTags criteria	-	curated The external catalog ID
tableTags object	The criteria for applying tags. Tags will be applied to all columns in a data source when this tag is found applied to the data source.	Optional	[]	-
tableTags.name string	The name of the data source tag. When matched, the classification tag will be applied to all columns within that data source.	Required if using tableTags criteria	-	-
tableTags.source string	The catalog the data source tag is from. curated is any tag in Immuta.	Required if using tableTags criteria	-	curated The external catalog ID

Framework reference

The framework reference is the response for many /frameworks requests. See the parameters described below.

Parameter	Description
id string	The Immuta-assigned unique ID for the framework.
version string	The Immuta-assigned unique ID for the version of this framework. This can be useful when auditing the changes to frameworks.
shortName string	The short, human-readable name for the framework.
name string	The official, human-readable name for the framework.
description string	A description of the framework.
createdBy integer	The unique ID of the user who created the framework.
createdAt timestamp	A timestamp of when the framework was created.
tags array[]	The tags used in the framework and the sensitivity attached to them. See the tags object description for child parameters.
rules array[]	The rules used to apply the tags in the framework. See the rules object description for child parameters.
active boolean	If true, the framework is actively being used on data sources in Immuta.