# Create a Project

## <mark style="color:green;">POST</mark> `/api/v2/project`

**Required Immuta permission**: `CREATE_PROJECT`

{% tabs %}
{% tab title="Basic project" %}

```yaml
name: A Bare Bones Project
projectKey: simplest possible project
```

{% endtab %}

{% tab title="Anyone project" %}
This project will be created with an **Anyone** subscription policy, where anyone can request and will automatically be granted access.

```yaml
name: Anyone Project
projectKey: Anyone project
documentation: "# Anyone Can See This"
description: "Anyone can join this project"
allowMaskedJoins: false
subscriptionPolicy:
    type: anyone
    automaticSubscription: true
    description: "Auto-subscribe everyone"
tags:
  - Discovered.Person Name
purposes:
  - Use Purposes
  - Purpose Hierarchy.Child 2.Grandchild 2
```

{% endtab %}

{% tab title="Approval required project" %}
This project will be created with an **Anyone who asks (and is approved)** subscription policy, where anyone can request access and they will get access when their request is approved.

```yaml
name: Approval Project
projectKey: Approval project
description: "Need approval to join this project"
allowMaskedJoins: true
subscriptionPolicy:
    type: approval
    approvals:
      - requiredPermission: GOVERNANCE
        specificApproverRequired: true
      - requiredPermission: ADMIN
        specificApproverRequired: false
```

{% endtab %}

{% tab title="Attribute-based access project" %}
This project will be created with an **Users with specific groups or attributes** subscription policy, where users with a specific attribute or in a specific group will automatically be granted access.

```yaml
name: Entitlement Project
projectKey: entitlement project
description: "Need specific entitlements to join this project"
subscriptionPolicy:
    type: entitlements
    automaticSubscription: false
    allowDiscovery: true
    entitlements:
      operator: any
      groups:
        - Engineers
        - Founders
      attributes:
        - name: Auth1
          value: super secret
```

{% endtab %}
{% endtabs %}

<details>

<summary>Projects with workspaces examples</summary>

**Project with Databricks Spark workspace**

```yaml
name: Databricks Spark Project
projectKey: databricks spark project
datasources:
  - Crime Data
  - Databricks Credit Card Transactions
  - Databricks Hipaa Data
purposes:
  - Use Purposes
workspace:
  type: databricks
  config:
    database: native
    directory: native
    workspaceConfigurationName: S3
```

**Project with Snowflake workspace**

```yaml
name: Snowflake Project
projectKey: snowflake project
datasources:
  - Snowflake Case
  - Snowflake Customer
  - Snowflake Web Sales
workspace:
  type: snowflake
  config:
    schema:
      SNOWFLAKE_NATIVE
    warehouses:
      - DEMO_WH
tags:
  - Discovered.Passport
```

</details>

## Path parameters

| Parameter                                        | Description                                                                                                             | Default value |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------- |
| **dryRun** `boolean`                             | If `true`, no updates will actually be made.                                                                            | `false`       |
| **deleteDataSourcesOnWorkspaceDelete** `boolean` | If `true`, will delete all data and the data sources associated with a project workspace when the workspace is deleted. | `false`       |

## Body parameters

| Attribute                                                     | Description                                                                                                                    | Required or optional | Default values                                           | Accepted values                                                |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
| **projectKey** `string`                                       | A key to uniquely identify this project for future API calls.                                                                  | Required             | -                                                        | -                                                              |
| **name** `string`                                             | The name of the project.                                                                                                       | Required             | -                                                        | -                                                              |
| **description** `string`                                      | A short description for the project.                                                                                           | Optional             | -                                                        | -                                                              |
| **documentation** `string`                                    | Markdown-supported documentation for this project.                                                                             | Optional             | -                                                        | -                                                              |
| **allowedMaskedJoins** `boolean`                              | If `true`, will allow joining on masked columns between data sources in this project. Only certain policies allow masked join. | Optional             | `false`                                                  | <ul><li><code>true</code></li><li><code>false</code></li></ul> |
| **purposes** `string[]`                                       | The list of purposes to add to this project.                                                                                   | Optional             | -                                                        | -                                                              |
| **datasources** `string[]`                                    | The list of data sources to add to this project.                                                                               | Optional             | -                                                        | -                                                              |
| [**subscriptionPolicy**](#subscriptionpolicy-object) `object` | The policy that determines which users can subscribe to the project.                                                           | Optional             | Defaults to manual subscription if the object is omitted | -                                                              |
| [**workspace**](#workspace-object) `object`                   | If this is a workspace project, this is the workspace configuration. The project will automatically be equalized.              | Optional             | -                                                        | -                                                              |
| **equalization** `boolean`                                    | If `true`, will normalize all users to the same entitlements so that everyone sees the same data.                              | Optional             | `false`                                                  | <ul><li><code>true</code></li><li><code>false</code></li></ul> |
| **tags** `array[]`                                            | Tags to add to the project.                                                                                                    | Optional             | -                                                        | -                                                              |

### `subscriptionPolicy` object

The `subscriptionPolicy` object allows you to define the policy for how users can subscribe to the project.

| Attribute                                         | Description                                                                                                             | Required or optional                   | Default values | Accepted values                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type** `string`                                 | The type of subscription policy the project will have.                                                                  | Required                               | -              | <ul><li><code>anyone</code>: Anyone can subscribe</li><li><code>approval</code>: Anyone can request approval and will be subscribed when it is approved</li><li><code>entitlements</code>: Users with the listed attributes or groups will be subscribed</li><li><code>manual</code>: Users must be manually added to be subscribed</li></ul> |
| **automaticSubscription** `boolean`               | If `true`, users will be automatically subscribed if they meet the policy requirements without any manual intervention. | Optional                               | `false`        | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                                                                                                                                                                                                                                                                |
| **description** `string`                          | A description of the policy.                                                                                            | Optional                               | -              | -                                                                                                                                                                                                                                                                                                                                             |
| [**approvals**](#approvals-array) `array[object]` | Details about the user that will approve subscription requests.                                                         | Required if **type** is `approval`     | -              | -                                                                                                                                                                                                                                                                                                                                             |
| [**entitlements**](#entitlements-object) `object` | Details about the entitlements required for users to subscribe to the project.                                          | Required if **type** is `entitlements` | -              | -                                                                                                                                                                                                                                                                                                                                             |

#### `approvals` array

This array is required if the policy **type** is `approval` in the [**subscriptionPolicy** object](#subscriptionpolicy-object). It allows you to define the users who can approve subscription requests.

| Attribute                              | Description                                                                                                                                                           | Required or optional               | Default values | Accepted values                                                                                       |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| **specificApproverRequired** `boolean` | If `true`, the user to approve the request will be selected by the user requesting access. If `false`, any user with the required permission can approve the request. | Required if **type** is `approval` | -              | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                        |
| **requiredPermission** `string`        | The required permissions for the user approving the subscription request.                                                                                             | Required if **type** is `approval` | -              | <ul><li><code>USER\_ADMIN</code></li><li><code>GOVERNANCE</code></li><li><code>AUDIT</code></li></ul> |

#### `entitlements` object

This object is required if the policy **type** is `entitlements` in the [**subscriptionPolicy** object](#subscriptionpolicy-object). It allows you to define the groups or attributes that users must have to subscribe to the project.

| Attribute                     | Description                                                                                                             | Required or optional                         | Default values | Accepted values                                             |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------- | ----------------------------------------------------------- |
| **operator** `string`         | Specify whether `all` of the circumstances must be met for the user to be subscribed (AND), or just `any` of them (OR). | Required if **type** is `entitlements`       | -              | <ul><li><code>all</code></li><li><code>any</code></li></ul> |
| **groups** `string`           | The name of the group the user must be a member of to subscribe to the project.                                         | Requires either **groups** or **attributes** | -              | -                                                           |
| **attributes** `object`       | Details about attributes the user must have to subscribe to the project.                                                | Requires either **groups** or **attributes** | -              | -                                                           |
| attributes.**name** `string`  | The name of the attribute the user must have to subscribe to the project. This is commonly referred to as a key.        | Required if using **attributes**             | -              | -                                                           |
| attributes.**value** `string` | The value of the attribute the user must have to subscribe to the project.                                              | Required if using **attributes**             | -              | -                                                           |

### `workspace` object

| Attribute                                      | Description                                                                                                                    | Required or optional                   | Default values | Accepted values                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | -------------- | ------------------------------------------------------------------------ |
| **type** `string`                              | The technology the workspace is in.                                                                                            | Required                               | -              | <ul><li><code>snowflake</code></li><li><code>databricks</code></li></ul> |
| **config** `object`                            | Details about the workspace configuration.                                                                                     | Required                               | -              | -                                                                        |
| config.**schema** `string`                     | Your project workspace will exist within this schema in Snowflake under the database configured by the application admin.      | Required when **type** is `snowflake`  | -              |                                                                          |
| config.**warehouses** `array`                  | These are the Snowflake warehouses that will be available to project members when they are working in the Snowflake workspace. | Required when **type** is `snowflake`  | -              |                                                                          |
| config.**database** `string`                   | The Databricks database the workspace will be in.                                                                              | Required when **type** is `databricks` | -              |                                                                          |
| config.**directory** `string`                  | The Databricks directory the workspace will be in.                                                                             | Required when **type** is `databricks` | -              |                                                                          |
| config.**workspaceConfigurationName** `string` | The Databricks workspace configuration name.                                                                                   | Required when **type** is `databricks` | -              |                                                                          |