Atlan API documentation

Update purpose

POST /api/service/purposes/{id}

Update a specific purpose based on its unique identifier.

Note that currently this is the only way to define policies for purposes as well. (Currently there is no separate endpoint through which to define policies individually.) Be aware that having many policies on a single purpose may lead to timeouts.

Path parameters

id string Required

Unique identifier of the purpose to update.

Body Required

Purpose with details to include in the update.

Note that if any policy attributes are included, then all policy attributes must be included (even if they are only empty arrays).

id string | null

Unique identifier of the purpose.
name string

Unique system name for the purpose. This will generally be the same as the displayName, but must be unique.
displayName string | null

Human-readable name of the purpose. This is what is shown on the UI, and while not strictly required for creation if it is missing then no name will be displayed for the purpose in the UI.
description string | null

Meaningful explanation for what the purpose represents or how it is used.
metadataPolicies array[object] | null Required

Instance of metadata policy on a purpose in Atlan, with its detailed information.
- actions array[string] | null
  List of granular permissions within the policy, to apply to assets with any of the classifications that are part of the purpose.
  
  Permissions are as follows:
  
  entity-read: view activity, lineage, custom metadata and SQL queries for processes in lineage or view definitions
  
  entity-update: update asset metadata including description, certification, owners, readme and resources
  
  entity-create: create new assets within the selected connection or specified database/schema (via API)
  
  entity-delete: delete assets within the selected connection or specified database/schema (via API)
  
  entity-update-business-metadata: update custom metadata values for the assets
  
  entity-add-classification: attach classifications to assets
  
  entity-remove-classification: remove classifications from assets
  Values are entity-read, entity-update, entity-create, entity-delete, entity-update-business-metadata, entity-add-classification, or entity-remove-classification.
- allow boolean | null
  
  If false, this applies an "explicit deny" to the listed permissions. Those permissions will not be granted to any users on the policy, even if those users are parts of other policies that do give them those permissions. In other words, this "explicit deny" will take precedence over all other permissions for the same classifications and users.
- name string | null
  
  Meaningful explanation of the policy.
- description string | null
  
  Unused.
- users array[string] | null
  
  List of unique usernames to whom the policy will apply.
- groups array[string] | null
  
  List of unique group names to whom the policy will apply. Note that these are the internal names of the groups, typically in all lowercase and without spaces.
- allUsers boolean | null
  
  When true, the policy will apply to all users in Atlan (present and future).
- type string
  
  Type of policy. For metadata policies, this should always be metadata.
dataPolicies array[object] | null Required

Instance of data policy on a purpose in Atlan, with its detailed information.
- actions array[string] | null
  
  List of granular permissions within the policy, to apply to assets with any of the classifications that are part of the purpose. For data policies the only possible permission is select, which applies to both previewing and querying data.
  
  Value is select.
- allow boolean | null
  
  If false, this applies an "explicit deny" to preview and query permission. This denial for previewing and querying applies to entire tables. So even if only a single column has a classification linked to this purpose, in the case of an "explicit deny" users in this policy will be unable to preview or query the entire table in which that column exists.
- name string | null
  
  Meaningful explanation of the policy.
- description string | null
  
  Unused.
- users array[string] | null
  
  List of unique usernames to whom the policy will apply.
- groups array[string] | null
  
  List of unique group names to whom the policy will apply. Note that these are the internal names of the groups, typically in all lowercase and without spaces.
- allUsers boolean | null
  
  When true, the policy will apply to all users in Atlan (present and future).
- type string | null
  
  Type of policy. To grant or deny access to data entirely (without masking), use access. To only mask the classified assets, use masking.
  
  Values are masking, access, or null.
- mask string | null
  
  Type of masking to apply when the type property is set to masking.
  
  Values are heka:MASK_SHOW_FIRST_4, heka:MASK_SHOW_LAST_4, heka:MASK_HASH, heka:MASK_NULL, heka:MASK_REDACT, or null.
tags array[string] | null Required

List of classifications that this purpose operates against.

Each name is the internal, uniquely hashed classification name and not the human-readable name of a classification.
readme string | null

URL-encoded HTML representing the richly-formatted readme for the purpose.

Responses

• 200 object

Purpose was updated successfully.
- id string | null
  
  Unique identifier of the purpose.
- name string
  
  Unique system name for the purpose. This will generally be the same as the displayName, but must be unique.
- displayName string | null
  
  Human-readable name of the purpose. This is what is shown on the UI, and while not strictly required for creation if it is missing then no name will be displayed for the purpose in the UI.
- description string | null
  
  Meaningful explanation for what the purpose represents or how it is used.
- metadataPolicies array[object] | null
  
  Instance of a metadata policy for a purpose in Atlan, with its detailed response-specific information.
  actions array[string] | null
  
  List of granular permissions within the policy, to apply to assets with any of the classifications that are part of the purpose.
  
  Permissions are as follows:
  
  entity-read: view activity, lineage, custom metadata and SQL queries for processes in lineage or view definitions
  
  entity-update: update asset metadata including description, certification, owners, readme and resources
  
  entity-create: create new assets within the selected connection or specified database/schema (via API)
  
  entity-delete: delete assets within the selected connection or specified database/schema (via API)
  
  entity-update-business-metadata: update custom metadata values for the assets
  
  entity-add-classification: attach classifications to assets
  
  entity-remove-classification: remove classifications from assets
  
  Values are entity-read, entity-update, entity-create, entity-delete, entity-update-business-metadata, entity-add-classification, or entity-remove-classification.
  
  allow boolean | null
  
  If false, this applies an "explicit deny" to the listed permissions. Those permissions will not be granted to any users on the policy, even if those users are parts of other policies that do give them those permissions. In other words, this "explicit deny" will take precedence over all other permissions for the same classifications and users.
  
  name string | null
  
  Meaningful explanation of the policy.
  
  description string | null
  
  Unused.
  
  users array[string] | null
  
  List of unique usernames to whom the policy will apply.
  
  groups array[string] | null
  
  List of unique group names to whom the policy will apply. Note that these are the internal names of the groups, typically in all lowercase and without spaces.
  
  allUsers boolean | null
  
  When true, the policy will apply to all users in Atlan (present and future).
  
  type string
  
  Type of policy. For metadata policies, this should always be metadata.
  
  createdAt integer(int64) | null
  
  Date and time (epoch) at which the policy was created, in milliseconds.
  
  createdBy string | null
  
  User who created the policy.
  
  updatedAt integer(int64) | null
  
  Date and time (epoch) at which the policy was last updated, in milliseconds.
  
  updatedBy string | null
  
  User who last updated the policy.
  
  id string | null
  
  Unique identifier (GUID) for the policy.
- dataPolicies array[object] | null
  
  Instance of a data policy for a purpose in Atlan, with its detailed response-specific information.
  actions array[string] | null
  
  List of granular permissions within the policy, to apply to assets with any of the classifications that are part of the purpose. For data policies the only possible permission is select, which applies to both previewing and querying data.
  
  Value is select.
  
  allow boolean | null
  
  If false, this applies an "explicit deny" to preview and query permission. This denial for previewing and querying applies to entire tables. So even if only a single column has a classification linked to this purpose, in the case of an "explicit deny" users in this policy will be unable to preview or query the entire table in which that column exists.
  
  name string | null
  
  Meaningful explanation of the policy.
  
  description string | null
  
  Unused.
  
  users array[string] | null
  
  List of unique usernames to whom the policy will apply.
  
  groups array[string] | null
  
  List of unique group names to whom the policy will apply. Note that these are the internal names of the groups, typically in all lowercase and without spaces.
  
  allUsers boolean | null
  
  When true, the policy will apply to all users in Atlan (present and future).
  
  type string | null
  
  Type of policy. To grant or deny access to data entirely (without masking), use access. To only mask the classified assets, use masking.
  
  Values are masking, access, or null.
  
  mask string | null
  
  Type of masking to apply when the type property is set to masking.
  
  Values are heka:MASK_SHOW_FIRST_4, heka:MASK_SHOW_LAST_4, heka:MASK_HASH, heka:MASK_NULL, heka:MASK_REDACT, or null.
  
  createdAt integer(int64) | null
  
  Date and time (epoch) at which the policy was created, in milliseconds.
  
  createdBy string | null
  
  User who created the policy.
  
  updatedAt integer(int64) | null
  
  Date and time (epoch) at which the policy was last updated, in milliseconds.
  
  updatedBy string | null
  
  User who last updated the policy.
  
  id string | null
  
  Unique identifier (GUID) for the policy.
- tags array[string] | null
  
  List of classifications that this purpose operates against.
  
  Each name is the internal, uniquely hashed classification name and not the human-readable name of a classification.
- readme string | null
  
  URL-encoded HTML representing the richly-formatted readme for the purpose.
- createdAt integer(int64) | null
  
  Date and time (epoch) at which the purpose was created, in milliseconds.
- createdBy string | null
  
  User who created the purpose.
- updatedAt integer(int64) | null
  
  Date and time (epoch) at which the purpose was last updated, in milliseconds.
- updatedBy string | null
  
  User who last updated the purpose.
- level string | null
  
  Level of the created purpose. (This will always be workspace.)
- version string | null
  
  Unique identity for the version of the purpose.
- enabled boolean | null
  
  True when this purpose is turned on, and false when it is turned off.
- resources string | null
- attributes object | null
- isActive boolean | null
  
  True when the purpose is currently enabled, false otherwise.
• 400 object

Bad request: typically because the purpose could not be found.
- code integer
  
  Unique code for the type of error that occurred.
- error string
  
  High-level description of the error. This will typically be the words keycloak error.
- info string | null
- message string
  
  More detailed message regarding the error that occurred.
- requestId string

POST /api/service/purposes/{id}

curl \
 -X POST https://tenant.atlan.com/api/service/purposes/3f35d508-4f43-48d3-84e3-889c13571f1c \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"name":"PII Protection","description":"Data protection for all personally-identifiable information.","tags":["rXlsT2vyr7mYtH1aCNLU6F"],"metadataPolicies":[{"actions":["entity-remove-classification"],"allow":false,"name":"Deny access to remove classifications","description":"","users":[],"groups":[],"allUsers":true,"type":"metadata"}],"dataPolicies":[{"actions":["select"],"mask":"heka:MASK_REDACT","allow":true,"name":"Redact all PII","description":"","users":[],"groups":[],"allUsers":true,"type":"masking"}]}'

Request example

{
  "name": "PII Protection",
  "description": "Data protection for all personally-identifiable information.",
  "tags": [
    "rXlsT2vyr7mYtH1aCNLU6F"
  ],
  "metadataPolicies": [
    {
      "actions": [
        "entity-remove-classification"
      ],
      "allow": false,
      "name": "Deny access to remove classifications",
      "description": "",
      "users": [],
      "groups": [],
      "allUsers": true,
      "type": "metadata"
    }
  ],
  "dataPolicies": [
    {
      "actions": [
        "select"
      ],
      "mask": "heka:MASK_REDACT",
      "allow": true,
      "name": "Redact all PII",
      "description": "",
      "users": [],
      "groups": [],
      "allUsers": true,
      "type": "masking"
    }
  ]
}

Response example (200)

{
  "id": "3f35d508-4f43-48d3-84e3-889c13571f1c",
  "version": "calm-sound-3764",
  "isActive": true,
  "createdAt": 1655214527401,
  "updatedAt": 1655218897319,
  "createdBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
  "updatedBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
  "description": null,
  "displayName": "PII Protection",
  "name": "PII Protection",
  "dataPolicies": [
    {
      "actions": [
        "select"
      ],
      "allUsers": true,
      "allow": true,
      "createdAt": 1655218897318,
      "createdBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
      "description": "",
      "groups": [],
      "id": "3ec4ac32-1068-43a2-b367-5862a099f77b",
      "mask": "heka:MASK_REDACT",
      "name": "Redact all PII",
      "type": "masking",
      "updatedAt": 1655218897318,
      "updatedBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
      "users": []
    }
  ],
  "metadataPolicies": [
    {
      "actions": [
        "entity-remove-classification"
      ],
      "allUsers": true,
      "allow": false,
      "createdAt": 1655218466881,
      "createdBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
      "description": "",
      "groups": [],
      "id": "60b55683-dd59-4e05-90a9-2779abc06c16",
      "name": "Deny access to remove classifications",
      "type": "metadata",
      "updatedAt": 1655218897318,
      "updatedBy": "service-account-apikey-e8d1f0bd-600e-4a8a-9248-b7c9aa1ef8c3",
      "users": []
    }
  ],
  "tags": [
    "rXlsT2vyr7mYtH1aCNLU6F"
  ],
  "level": "workspace",
  "enabled": true,
  "readme": null,
  "resources": null,
  "attributes": null
}

Response example (400)

{
  "code": 3500,
  "error": "keycloak error",
  "info": "string",
  "message": "Got invalid status code from keycloak",
  "requestId": "2PYHURjODyNywCwRDHtK4lWoepxkoxYd"
}