# Custom Application

### Overview

The Custom Application Template can be used to model most applications and services. It can describe many common entity types (such as users, groups, and resources), and should be the starting point for most custom connectors.

The template has three primary elements, covered in detail in this document:

* **Applications** - describes one or more application instances for the custom data source. An application may consist of any of the following entities:
  * **Local Users** - defines the users of the application. The local user entity can be used to store the properties of the user specific to the application (such as `last_login_at`) and can be linked to a source identity like Okta or AzureAD.
  * **Local Groups** - defines a group of users, permissions to the application or resources can be assigned to a group.
  * **Local Roles** - defines a collection of permissions. A role can be used to link an identity (local user, group, or IdP) to an application or resource. An identity assigned to a role will be assigned all permissions from that role.
  * **Local Access Credentials** - defines API keys, tokens, certificates, or other non-human authentication methods used by applications or services.
  * **Resources** - for more fine grain authorization tracking resources can be used to represent components of the application that have their own authorization. Users and groups can be assigned permission or roles to resources.
    * **Sub Resources** - resources can additionally have sub-resources for additional levels of depth.
* **Permissions** - define the applications specific permissions and map to Veza canonical permissions.
* **Identity to Permissions** - Assign local and federated users and groups to permissions or roles to the application and resources.
* Additionally, a [custom property definition](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-custom-properties.md) may describe user-configured key:pair values that can be applied to entities in the payload.

To use the generic app template, set the template type to `application` when creating a new data provider:

```bash
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
--compressed --data-binary '{"name":"DemoApp","custom_template":"application"}'
```

#### Enabling Lifecycle Management with SCIM

If your custom application exposes SCIM 2.0 compliant endpoints, you can enable automated provisioning and deprovisioning through Veza Lifecycle Management and Access Requests by setting the `external_lifecycle_management_type` parameter to `SCIM`:

```bash
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{
  "name": "MyCustomApp",
  "custom_template": "application",
  "external_lifecycle_management_type": "SCIM"
}'
```

This enables Veza to automate user provisioning, deprovisioning, and group membership management for your custom application. For detailed configuration and supported operations, see [Custom Application with SCIM (OAA)](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/integrations/oaa-scim.md).

### Sample Payload

<details>

<summary>Simple Custom Application</summary>

This example demonstrates using local users and groups to assign permissions directly to the application and resources.

```json
{
  "custom_property_definition": {
    "applications": [
      {
        "application_type": "sample",
        "application_properties": {},
        "local_user_properties": {},
        "local_group_properties": {},
        "local_role_properties": {},
        "resources": []
      }
    ]
  },
  "applications": [
    {
      "name": "Sample App",
      "application_type": "sample",
      "description": "This is a sample app",
      "local_users": [
        {
          "id": "0000000001",
          "name": "bob",
          "identities": [
            "bob@example.com"
          ],
          "is_active": true,
          "created_at": "2022-01-26T20:48:12.460Z"
        },
        {
          "id": "0000000002",
          "name": "jane",
          "identities": [
            "jane@example.com"
          ],
          "groups": [
            "admins"
          ],
          "created_at": "2021-08-13T06:28:13.250Z"
        }
      ],
      "local_groups": [
        {
          "id": "admins",
          "name": "Administrators"
        }
      ],
      "local_roles": [],
      "tags": [],
      "custom_properties": {},
      "resources": [
        {
          "id": "0001",
          "name": "Entity1",
          "resource_type": "thing",
          "description": "Some entity in the application",
          "sub_resources": [
            {
              "name": "Child 1",
              "resource_type": "child",
              "description": "My information about resource"
            }
          ]
        },
        {
          "id": "0002",
          "name": "Entity2",
          "resource_type": "thing",
          "description": "Another entity in the application"
        }
      ]
    }
  ],
  "permissions": [
    {
      "name": "admin",
      "permission_type": [
        "DataRead",
        "DataWrite"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    },
    {
      "name": "operator",
      "permission_type": [
        "DataRead",
        "MetadataRead"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    },
    {
      "name": "manager",
      "permission_type": [
        "MetadataWrite"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    }
  ],
  "identity_to_permissions": [
    {
      "identity": "0000000001",
      "identity_type": "local_user",
      "application_permissions": [
        {
          "application": "Sample App",
          "permission": "operator",
          "apply_to_application": true
        },
        {
          "application": "Sample App",
          "resources": [
            "0001"
          ],
          "permission": "manager"
        }
      ]
    },
    {
      "identity": "admins",
      "identity_type": "local_group",
      "application_permissions": [
        {
          "application": "Sample App",
          "permission": "admin",
          "apply_to_application": true
        }
      ]
    }
  ]
}
```

</details>

<details>

<summary>Sample Application using Roles</summary>

```json
{
  "applications": [
    {
      "name": "Sample App",
      "application_type": "sample",
      "description": "This is a sample app",
      "local_users": [
        {
          "name": "bob",
          "identities": [
            "bob@example.com"
          ],
          "is_active": true,
          "created_at": "2022-01-26T20:48:12.460Z",
          "id": "0000000001"
        },
        {
          "name": "jane",
          "identities": [
            "jane@example.com"
          ],
          "created_at": "2021-08-13T06:28:13.250Z",
          "id": "0000000002"
        }
      ],
      "local_groups": [],
      "local_roles": [
        {
          "id": "admin",
          "name": "Administrator",
          "permissions": [
            "manage_users"
          ],
          "tags": [],
          "custom_properties": {}
        },
        {
          "id": "user",
          "name": "User",
          "permissions": [
            "view_tickets",
            "close_tickets"
          ],
          "tags": [],
          "custom_properties": {}
        }
      ],
      "tags": [],
      "custom_properties": {},
      "resources": []
    }
  ],
  "permissions": [
    {
      "name": "manage_users",
      "permission_type": [
        "MetadataWrite"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    },
    {
      "name": "view_tickets",
      "permission_type": [
        "DataRead"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    },
    {
      "name": "close_tickets",
      "permission_type": [
        "MetadataWrite"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    }
  ],
  "identity_to_permissions": [
    {
      "identity": "0000000001",
      "identity_type": "local_user",
      "role_assignments": [
        {
          "application": "Sample App",
          "role": "user",
          "apply_to_application": true,
          "resources": []
        }
      ]
    },
    {
      "identity": "0000000002",
      "identity_type": "local_user",
      "role_assignments": [
        {
          "application": "Sample App",
          "role": "user",
          "apply_to_application": true,
          "resources": []
        },
        {
          "application": "Sample App",
          "role": "admin",
          "apply_to_application": true,
          "resources": []
        }
      ]
    }
  ]
}
```

</details>

#### Custom Properties and Tags

[Custom properties](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-custom-properties.md) and [Veza Tags](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-tags.md) can be applied to most objects in the OAA payload: the `application` and its `local_users`, `local_groups`, `local_roles` and `resources`/`sub_resources`.

**Define custom properties**

```json
  "custom_property_definition": {
    "applications": [
      {
        "application_type": "sample",
        "application_properties": {},
        "local_user_properties": {
          "license_type": "STRING",
          "license_expires": "TIMESTAMP"
        },
        "local_group_properties": {},
        "local_role_properties": {},
        "role_assignment_properties": {},
        "access_cred_properties": {},
        "resources": []
      }
    ]
  }
```

#### Set custom properties

In the rest of the payload, for each object that should have additional properties, add a `custom_properties` array containing the property keys and values:

```json
      "local_users": [
        {
          "id": "001010",
          "name": "bob",
          "identities": [
            "bob@example.com"
          ],
          "groups": null,
          "is_active": true,
          "created_at": "2022-01-26T20:48:12.460Z",
          "last_login_at": null,
          "deactivated_at": null,
          "password_last_changed_at": null,
          "tags": [],
          "custom_properties": {
            "license_type": "pro",
            "license_expires": "2023-01-01T00:00:00.000Z"
          }
        }
      ]
```

> *Use incremental updates to remove tags*: Resubmitting a payload with different tags will apply any new tags, but not remove existing ones. To remove a tag already applied to an entity, you will need to use the [incremental update](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/incremental-updates.md) `remove_tag` operation.

**Validation and Troubleshooting**

The API response will provide information for invalid data submission. You can check Veza events for updates on parsing status. Errors won't typically occur during parsing, as the metadata is validated upon push. To ensure a valid payload, you should:

* Confirm all string fields are are valid UTF-8 strings no larger than 256 bytes.
* Check that all required fields are present. Tags and properties are optional. You can null empty groups, roles, and other "empty" but required keys.
* A 200 OK response may include warnings when matching IDP identities can't be found

### Applications

The OAA payload must contain at least one top-level application. To model data systems with multiple components (such as different servers or repositories), applications can have resources and sub-resources.

You can also specify more than one application in the OAA payload, each with its own identities, permissions, roles, and resources.

The `application_type`is applied to all application resources and identities, and can be used as a filterable property in Veza search.

```json
{
  "applications": [
    {
      "name": "Custom App",
      "application_type": "Source Control",
      "description": "Has a resource for each repository",
      "custom_properties": {},
      "tags": [],
      "owners": [],
      "local_users": [],
      "local_groups": [],
      "local_roles": [],
      "resources": []
    }
  ]
}
```

#### Application Properties

| Field                | Type       | Description                                                                                                                                                                                                                                                                                                                                  |
| -------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`               | string     | Identifies the app in Veza Search. Used to bind permissions to the application                                                                                                                                                                                                                                                               |
| `application_type`   | string     | Applied to all entities within the application as a searchable property. Multiple instances of an application can share the same type                                                                                                                                                                                                        |
| `description`        | string     | Any additional notes to show in the entity details, limit 256 characters                                                                                                                                                                                                                                                                     |
| `custom_properties`  | dictionary | [Custom Properties](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-custom-properties.md) contain `property_values` validated against the `custom_property_definition`                                                                                                                                                           |
| `tags`               | array      | Specify tags with a key and optional value (optional)                                                                                                                                                                                                                                                                                        |
| `owners`             | array      | See [Entity Owners](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-entity-owners.md)                                                                                                                                                                                                                                            |
| `local_users`        | array      | Contains zero or more local users (see [local\_identities](#identities)).                                                                                                                                                                                                                                                                    |
| `local_groups`       | array      | Contains zero or more [local groups](#identities) (collections of users).                                                                                                                                                                                                                                                                    |
| `local_roles`        | array      | Defines permissions for any [roles](#local-roles) within the application.                                                                                                                                                                                                                                                                    |
| `local_access_creds` | array      | Contains any [access credentials](#local-access-credentials) for the application.                                                                                                                                                                                                                                                            |
| `local_agents`       | array      | Contains any AI agent entities for the application.                                                                                                                                                                                                                                                                                          |
| `local_models`       | array      | Contains any AI model entities for the application.                                                                                                                                                                                                                                                                                          |
| `resources`          | array      | Contains any [resources](#resources) and sub-resources.                                                                                                                                                                                                                                                                                      |
| `okta_app_id`        | string     | (Optional, early access) The Okta Application ID for this application. When set, Veza enriches local users with `sso_last_login_at` timestamps from Okta SSO activity. Requires the `INTEG_OAA_SSO_LAST_LOGIN` feature flag. See [Okta SSO last login enrichment](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/okta-sso-last-login.md). |

**Optional fields**: some values in the schema are optional. When submitting a payload without a required field, an error message will help identify the issue. The following guidelines apply:

* Any type of data in a JSON payload can be null (not set).
* Unused optional arrays and objects should be empty `{}` or `[]`.
* Unused optional strings, numbers, and booleans should be null.
* Strings and string lists intended to have constant values (enums) such as `identity_type` may have a default value when not set.

OAA apps need to contain at least one identity, which could be a `local_group`, `local_role`, or an IdP identity. Role assignments are made in the [`identity_to_permissions`](#identities-to-permissions-mapping) section.

### Resources

Each application can contain one or more resources that users can access. Resources can have additional searchable properties and may contain additional sub-resources.

**Sub-resources** describe additional layers of the application principals can have authorization to, and support the same properties as resources, including additionally nested sub-resources.

```json
"resources": [
  {
    "name": "Entity1",
    "id": "Unique ID",
    "resource_type": "thing",
    "description": "Some entity in the application",
    "sub_resources": [
      {
        "name": "Child 1",
        "resource_type": "child",
        "description": "My information about resource",
        "sub_resources": [],
        "custom_properties": {},
        "tags": [],
        "owners": []
      }
    ],
    "custom_properties": {},
    "tags": [],
    "owners": []
  },
  {
    "name": "Entity2",
    "id": "Another Unique ID",
    "resource_type": "thing",
    "description": "Another entity in the application",
    "sub_resources": [],
    "custom_properties": {},
    "tags": [],
    "owners": [],
  }
]
```

#### Resource Properties

An application can have any number of nested sub resources.

| Field               | Type                                          | Description                                                                                                                          |
| ------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `name`              | string                                        | Resource name. Primary ID for mapping users to individual resource permissions.                                                      |
| `id`                | string                                        | Optional value to use as the unique ID, instead of the resource `name`\*.                                                            |
| `resource_type`     | string                                        | Searchable label for the resource type. The application entity details in Veza will show the contained resource types as properties. |
| `description`       | string                                        | Shown in Veza entity details, max 255 characters.                                                                                    |
| `custom_properties` | dictionary                                    | See [Custom Properties](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-custom-properties.md).                           |
| `sub_resources`     | array                                         | Used for additional resource layers, nested data sources, services, and so on.                                                       |
| `connections`       | [Resource Connections](#resource-connections) | Optional list of resource connections to external entities discovered by Veza                                                        |
| `tags`              | array                                         | Specify tags with a key and optional value (optional)                                                                                |
| `owners`            | array                                         | See [Entity Owners](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-entity-owners.md)                                    |

\* A specific resource type must have only resources with an `id`, or only resources without an `id`. When used `identity_to_permissions` assignments are made by the `id` value and `name` functions as a display name.

#### Resource Connections

> In the system being modeled, application resources and sub-resources (such as virtual machines or Looker views) have access to other entities in the Veza Access Graph.

If an application resource or sub-resource is able to assume the permissions of a local user, IAM role, or Enterprise application, you can specify the `connections` to another graph entity `node_type` and `id`:

```json
{
  "name": "cog1",
  "resource_type": "cog",
  "connections": [
    {
      "id": "service_account@some-project.iam.gserviceaccount.com",
      "node_type": "GoogleCloudServiceAccount"
     }
  ]
}
```

The following node types are currently available:

* `SnowflakeUser`
* `GoogleCloudServiceAccount`
* `AwsIamRole`
* `AzureADEnterpriseApplication`
* `TrinoUser`

### Identities

Applications can have local users and groups for identities. For users and groups that correlate to an external Identity Provider (for example accounts automatically provisioned by the IdP), you can map the principal to the IdP entity name or login email in `identities`.

#### Local Users

Contains any users whose profiles and authentication are handled and stored by the custom application. Local users include their group assignments and any federated identities that should be mapped to the local user:

```json
"local_users": [
  {
    "id": "egray",
    "name": "Evan Gray",
    "email": "egray@example.com",
    "identities": ["egray@example.com"],
    "groups": ["contractors"],
    "is_active": true,
    "created_at": "2020-12-19T16:39:57-08:00",
    "last_login_at": "2021-11-19T14:19:30-08:00",
    "password_last_changed_at": null,
    "deactivated_at": null,
    "custom_properties": {},
    "tags": [],
    "owners": []
   }
]
```

| Field                      | Type                                      | Description                                                                                                                                                                                                                                                                     |
| -------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                     | string                                    | Name of the local user, shown in the Veza UI.                                                                                                                                                                                                                                   |
| `id`                       | string                                    | Optional identifier to use for mapping users to groups, roles, and permissions.                                                                                                                                                                                                 |
| `email`                    | string                                    | User email address (optional). Separate from `identities`, this is a display/metadata field on the user entity.                                                                                                                                                                 |
| `identities`               | identities array                          | Maps the user to a federated identity by login email or group name. Use when your IdP provisions local accounts, or if the local user can be assumed by an external group. Must match a discovered Okta, Google Workspace, or Azure AD entity Name, PrincipalName, or Identity. |
| `groups`                   | groups array                              | List of any [group](#local-groups) memberships as strings. Must exist in local groups.                                                                                                                                                                                          |
| `access_creds`             | array                                     | List of `local_access_creds` IDs associated with this user (optional).                                                                                                                                                                                                          |
| `is_active`                | boolean                                   | If activity state is available from the provider, use this field to make the value available as a searchable property (optional).                                                                                                                                               |
| `user_type`                | string                                    | Distinguishes between `human` and `service_account` user types (optional). Useful for identifying non-human accounts in access reviews.                                                                                                                                         |
| `principal_id`             | string                                    | The ID for this user in a linked principal template, used for automatic connection. If not supplied, the user `id` is used (optional).                                                                                                                                          |
| `created_at`               | RFC3339 string                            | User creation date (optional), for example `1996-12-19T16:39:57-08:00`.                                                                                                                                                                                                         |
| `last_login_at`            | RFC3339 string                            | (optional)                                                                                                                                                                                                                                                                      |
| `password_last_changed_at` | RFC3339 string                            | (optional)                                                                                                                                                                                                                                                                      |
| `deactivated_at`           | RFC3339 string                            | (optional)                                                                                                                                                                                                                                                                      |
| `access_creds`             | array                                     | List of access credential `id` values associated with this user (optional). Links the user to their API keys, tokens, or other credentials defined in `local_access_creds`.                                                                                                     |
| `custom_properties`        | dictionary                                | See [Custom Properties](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-custom-properties.md).                                                                                                                                                                      |
| `tags`                     | [tags](#custom-properties-and-tags) array | Specify tags with a key and optional value (optional).                                                                                                                                                                                                                          |
| `owners`                   | array                                     | See [Entity Owners](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-entity-owners.md)                                                                                                                                                                               |

#### local Groups

```json
"local_groups": [
  {
    "name": "US Contractors",
    "id": "us-contractors",
    "identities": ["user1@company.com"],
    "groups": [
      "all-contractors",
      "all-workers"
    ],
    "tags": [],
    "owners": []
  }
]
```

If the application has any groups, describe each one in the `local_groups` array.

> Group assignments for entities are defined in `identity_to_permissions`.

| Field               | Type           | Description                                                                                                         |
| ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `name`              | string         | Name of the local group. Primary ID for mapping group to permissions.                                               |
| `id`                | string         | Optional identifier to use for permissions mapping.                                                                 |
| `identities`        | array          | If IdP users are members of the local group, or if the local group directly maps to an IdP group, list them here.\* |
| `groups`            | array          | List of local groups this group is a **member of** (for applications that support adding groups to other groups).   |
| `access_creds`      | array          | List of `local_access_creds` IDs associated with this group (optional).                                             |
| `created_at`        | RFC3339 string | Group creation date (optional).                                                                                     |
| `custom_properties` | dictionary     | See [Custom Properties](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-custom-properties.md).          |
| `tags`              | array          | Specify tags with a key and optional value (optional).                                                              |
| `owners`            | array          | See [Entity Owners](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-entity-owners.md).                  |

\*Must match a discovered Okta or Azure entity Name, PrincipalName, or Identity

#### Local Roles

```json
"local_roles": [
    {
        "name": "administrator",
        "id": "0001",
        "permissions": ["create","destroy"]
    },
    {
        "name": "operator",
        "id": "0002",
        "permissions": ["pull", "read"],
        "tags": [],
        "owners": []
    }
]
```

Local roles define collections of local permissions that can be assigned to multiple resources. In the `applications` section, roles are named and mapped to permissions. Role assignments are defined in `identity_to_permissions`.

| Field               | Type       | Description                                                                                                                                   |
| ------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | string     | Name of the local role. Primary ID for mapping role to permissions.                                                                           |
| `id`                | string     | Optional identifier to use for permissions mapping.                                                                                           |
| `permissions`       | array      | Permissions associated with the role. Must exist in `permissions`.                                                                            |
| `roles`             | array      | List of sub-role names for nested role hierarchies (optional). An identity assigned to this role inherits all permissions from its sub-roles. |
| `custom_properties` | dictionary | See [Custom Properties](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-custom-properties.md).                                    |
| `tags`              | array      | Specify tags with a key and optional value (optional).                                                                                        |
| `owners`            | array      | See [Entity Owners](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-entity-owners.md).                                            |

#### Local Access Credentials

Access credentials represent API keys, tokens, certificates, or other non-human authentication methods used by applications or services.

```json
"local_access_creds": [
  {
    "name": "Production API Key",
    "id": "prod-key-001",
    "created_at": "2023-01-15T08:00:00.000Z",
    "expires_at": "2024-01-15T08:00:00.000Z",
    "last_used_at": "2023-12-01T14:30:00.000Z",
    "can_expire": true,
    "is_active": true,
    "custom_properties": {},
    "tags": [],
    "owners": []
  }
]
```

| Field               | Type           | Description                                                                                               |
| ------------------- | -------------- | --------------------------------------------------------------------------------------------------------- |
| `name`              | string         | Name of the access credential                                                                             |
| `id`                | string         | Unique identifier for the credential                                                                      |
| `created_at`        | RFC3339 string | When the credential was created (optional)                                                                |
| `expires_at`        | RFC3339 string | When the credential expires (optional)                                                                    |
| `last_used_at`      | RFC3339 string | Last time the credential was used (optional)                                                              |
| `can_expire`        | boolean        | Whether the credential can expire                                                                         |
| `is_active`         | boolean        | Whether the credential is currently active                                                                |
| `custom_properties` | dictionary     | See [Custom Properties](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-custom-properties.md) |
| `tags`              | array          | See [Veza Tags](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-tags.md)                      |
| `owners`            | array          | See [Entity Owners](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/oaa-entity-owners.md)         |

**`permissions`**

```json
"permissions": [
   {
     "name": "Admin",
     "permission_type": [
       "DataRead",
       "DataWrite",
       "MetadataRead",
       "MetadataWrite"
     ]
   },
   {
     "name": "Operator",
     "permission_type": [
       "MetadataRead",
       "DataRead"
     ]
   },
   {
     "name": "Inactive",
     "permission_type": [
       "NonData"
     ]
   }
 ]
```

Bind local permissions to the corresponding Veza canonical permission(s). Each native application permission should be included as an object, mapped to the corresponding data/non-data actions it allows.

Canonical permission types are:

* `DataRead`
* `DataWrite`
* `MetadataRead`
* `MetadataWrite`
* `NonData`
* `DataCreate`
* `DataDelete`
* `MetadataCreate`
* `MetadataDelete`
* `Uncategorized`

| Field                    | Type   | Description                                                                                                                                                                                                                 |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                   | string | Native permission name, such as “Push” (used to bind local and IdP identities to native permissions).                                                                                                                       |
| `permission_type`        | enum   | List of canonical privilege(s) the permission represents.                                                                                                                                                                   |
| `apply_to_sub_resources` | bool   | To more accurately model applications where permissions should apply to any children of a resource, set TRUE to define the permission as inheritable. This eliminates the need to include the permission at each sub level. |
| `resource_types`         | array  | Optional list of resource type strings. When specified, separate permission nodes are created per resource type. See below.                                                                                                 |

To better model systems where roles can contain different permissions to different types of resources, `permissions` can apply to individual `resource_types`.

* When the payload is parsed, individual permissions are created for each type of resource the permission applies to.
* Without `resource_types` specified, the permission will function normally. When directly connecting principals and resources, `resource_type` is ignored.

#### `identity_to_permissions`

```json
"identity_to_permissions": [
     {
       "identity": "Evan Gray",
       "identity_type": "local_user",
       "application_permissions": [
          {
           "application": "Veza AI",
           "resources": ["terraform-dev", "prod"],
           "permission": "pull"
         },
         {
           "application": "Veza AI",
           "resources": ["terraform-dev", "prod"],
           "permission": "push"
         }
       ]
     }
   ]
```

Contains an object for each local and IdP identity, and the individual permissions to applications and resources.

* You can bind permissions to federated users and groups by providing the principal’s IDP login email or group name as the `identity`, and setting the `identity_type` to `idp`.
* Permissions and role assignments can apply to the entire application or scoped to specific resources.
* For each identity (matching a local user, group, or IdP identity), state the identity type and add the assigned permissions/roles:

| Field                     | Type   | Description                                                                                                         |
| ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `identity`                | string | Principal name or email address. Maps to IdP login email or group name.                                             |
| `identity_type`           | string | Sets whether the identity corresponds to an IdP identity, or is local to the application                            |
| `application_permissions` | array  | List each local permission available to the identity (must be a valid permission `name` from the previous section). |
| `role_assignments`        | array  | Any roles assigned to the identity, and the resources they apply to (role/resource must exist in `applications`).   |

* Each `identity` can be either a `local_user`, `local_role`, `local_group`, or `local_access_creds` name, or the identifier of an IdP user, group, or role (email address or group name).
* `identity_type` must be one of: `idp` (default), `local_user`, `local_group`, `local_role`, or `local_access_creds`.

**`application_permissions`**

```json
{
    "identity": "idpuser@org.co",
    "identity_type": "idp",
    "application_permissions":
    [
        {
            "application": "source control",
            "resources": ["util-tools", "terraform"],
            "apply_to_application": false,
            "permission": "write"
        },
        {
            "application": "source control",
            "resources": [],
            "apply_to_application": true,
            "permission": "read"
        }
    ]
}
```

Binds the `identity` (IdP entity, local user, or local group) to local permission, by `application` and `resources`.

| Field                  | Type    | Description                                                                                                        |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `application`          | string  | Maps to an application `name` from the first section. Must exist in `applications`                                 |
| `resources`            | array   | List of application resource or sub-resource `name`s to apply the permission. Must exist in `applications`         |
| `apply_to_application` | boolean | Set to `true` to model environments where permissions apply to the top-level application as well as its resources. |
| `permission`           | string  | Maps to a permission `name` from the second section. Must exist in `permissions`                                   |

**`role_assignments`**

Local roles are assigned to identities in the `role_assignments` array. Roles can apply to the entire application or only to specific (sub) `resources`.

```json
{
    "identity": "john_smith",
    "identity_type": "local_user",
    "role_assignments":[
        {
            "application": "custom application",
            "role": "administrator",
            "apply_to_application": true,
            "resources": []
        },
        {
            "application": "custom application",
            "role": "ops",
            "apply_to_application": false,
            "resources": ["oaa-vm-1"]
        }
    ]
}
```

| Field                   | Type       | Description                                                                                                                                                                                                                              |
| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `application`           | string     | The application where the role applies. Must exist in `applications`                                                                                                                                                                     |
| `role`                  | string     | The role name. Must exist in `local_roles`                                                                                                                                                                                               |
| `apply_to_application`  | boolean    | Set to `true` to model environments where the role applies to the top-level application and all its resources.                                                                                                                           |
| `resources`             | array      | List of resources and sub-resources where the role applies. Must exist in `applications`                                                                                                                                                 |
| `assignment_properties` | dictionary | Custom properties on the role assignment itself (optional). Must be defined in `role_assignment_properties` within `custom_property_definition`. Useful for tracking assignment-specific metadata such as assignment date or expiration. |

### Identities to Permissions mapping

The `identity_to_permissions` array defines how identities are authorized to applications and resources. Each entry maps an identity to its application permissions and/or role assignments. See the [identity\_to\_permissions](#identity_to_permissions) section above for field details.

```json
  "identity_to_permissions": [
    {
      "identity": "0000000001",
      "identity_type": "local_user",
      "role_assignments": [
        {
          "application": "Sample App",
          "role": "user",
          "apply_to_application": true,
          "resources": []
        }
      ]
    },
    {
      "identity": "0000000002",
      "identity_type": "local_user",
      "role_assignments": [
        {
          "application": "Sample App",
          "role": "user",
          "apply_to_application": true,
          "resources": []
        },
        {
          "application": "Sample App",
          "role": "admin",
          "apply_to_application": true,
          "resources": []
        }
      ]
    }
  ]

```


---

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

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/custom-application-template.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.