---
title: "Create a project"
description: "Create a project in a folder, give people access to it as you create it, and grant or remove access later."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a project

Creating a project can also place it in a [folder](/organizations/folders) and give users,
groups and bots access to it, in one step. If any part is refused, nothing is created.

## Before you start

- You need `projects.create` (in `ProjectsFullAccess`).
- To give access as you create it, you also need `policies.attach` (in `IAMFullAccess`).
- An organization can have 10 projects by default. See
  [Project quota](/organizations#project-quota).

## Project access

A project can give two levels of access of its own:

| Level | Allows, in the project and on everything in it |
| --- | --- |
| **Full access** (`full`) | Every action. |
| **Read-only** (`readOnly`) | Every list and read action, as `ReadOnlyAccess` allows, including those of products added later. |

Each level is a policy that belongs to the project, named `<project> full access` and
`<project> read-only`:

- Its name follows the project's name, and it can't be edited or deleted. Attach and detach it
  like any policy, with `policies.attach`.
- It's deleted with the project, and everyone loses it.
- It grants nothing on the organization itself. People also need a policy such as `BasicAccess`
  to see the organization, and the folder the project sits in.
- IAM's policy list leaves project access policies out. The project's **Access** tab (it needs
  `policies.list`) shows who has each level, and a user's, bot's or group's **Permissions** tab
  shows the ones attached to them.

Other policies can also reach a project: `AdministratorAccess`, `ReadOnlyAccess`, a product's
full-access policy, or a custom policy that names the project.

If your own policies name specific projects, rather than every project, give yourself access
as you create the project, which needs `policies.attach`. Otherwise you may not be able to see
the project once it's created; without `policies.attach`, ask someone who has it to grant you
access afterwards.

## Create a project

### Console

1. Open **Projects** and click **Create project**. To create it in a folder, you can also open
the folder and click **Create project** there.
2. Enter a **Name**, and choose a **Folder**, or leave the project at the top level.
3. Under **Access**, choose who gets **Full access** or **Read-only**. The form starts with you
at Full access, unless you're the root user; **Add** adds a row. The **Access** section shows
only if you have `policies.attach`, and offers users, groups and bots: give EZGH SSO directory
users and groups access with the CLI or API.
4. Click **Create project**.

The console then opens the new project and makes it the current project.
### CLI

```sh
ezgh projects create payments-prod \
  --folder Engineering/Payments \
  --grant user:me=full \
  --grant group:payments-team=full \
  --grant group:auditors=readOnly
```

Each `--grant` is `<type>:<who>=full|readOnly`:

| Type | Who |
| --- | --- |
| `user` | A user ID, an email, or `me` |
| `bot` | A bot ID, slug or name, or `me` when you use the bot's API key |
| `group` | A group ID, slug or name |
| `ssoUser` | An [EZGH SSO](/sso) directory user's resource name, ID, email or slug |
| `ssoGroup` | An EZGH SSO directory group's resource name, ID, slug or name |

`--folder` takes a folder's ID, slug, name or path. Leave it out to create the project at the
top of the organization.
### API

```sh
curl -X POST https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/projects \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "payments-prod",
    "folderId": "0199a3c5-1b2c-7d3e-8f40-5a6b7c8d9e0f",
    "access": [
      { "principal": { "type": "user", "id": "jtMJ8kQ2xW4nR7pL5vB3cD9f" }, "level": "full" },
      { "principal": { "type": "group", "id": "0199a3c6-2c3d-7e4f-9a50-6b7c8d9e0f1a" }, "level": "readOnly" }
    ]
  }'
```

- `folderId` is a folder's `id`; leave it out for the top of the organization.
- `access` holds up to 10 entries, each principal once. `type` is `user`, `bot`, `group`,
`ssoUser` or `ssoGroup`. Users are named by user ID, bots and groups by `id`, and EZGH SSO
directory users and groups by resource name.
- Each principal, and the folder, must be the organization's (`404` otherwise). Over the project
quota, the response is `409 quota_exceeded`. If EZGH SSO principals can't be looked up at the
moment, the response is `429` with `Retry-After`, or `503`; retry with the same
`Idempotency-Key`.
- EZGH SSO directory users and groups get only the actions that apply to them (see
[IAM for directory users](/sso/access-control#iam-for-directory-users)); a level that grants
them nothing is refused (`400`).
- The response is `201` with the project, which has `folderId`. See
[CreateProject](/orgs-api/projects/CreateProject/).

The root user always has `AdministratorAccess`, so it can't be given project access: leave it
out (`403`).

## Grant access later

Granting access to an existing project needs `projects.get` on the project and
`policies.attach`. People who already have a level keep it.

### Console

Open the project, then the **Access** tab, and click **Grant access**. Choose who gets
**Full access** or **Read-only**, then click **Grant access**.
### CLI

```sh
ezgh projects grant payments-prod --grant user:ada@acme.test=readOnly
```

The CLI prints the project's access policies with their IDs.
### API

```sh
curl -X POST https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID/access \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "access": [ { "principal": { "type": "user", "id": "jtMJ8kQ2xW4nR7pL5vB3cD9f" }, "level": "readOnly" } ] }'
```

`access` takes the same entries as on create, at least one. The response is `200` with
`{ "policies": [...] }`, the project's access policies. See
[GrantProjectAccess](/orgs-api/projects/GrantProjectAccess/).

## Remove access

Removing access detaches the project's policy, with `policies.attach`.

### Console

Open the project, then the **Access** tab, and click **Remove** next to the user, group or bot, then confirm. EZGH SSO directory users and
groups aren't listed there by name: detach their policy with the CLI or API.
### CLI

```sh
ezgh iam policies detach $POLICY_ID --user ada@acme.test
```

`ezgh projects grant` prints the policy IDs.
### API

The project's access policy IDs are in the
[GrantProjectAccess](/orgs-api/projects/GrantProjectAccess/) response, or list them with
[ListPolicies](/orgs-api/policies/ListPolicies/) and `?projectId=$PROJECT_ID` (it needs
`policies.list`). Then detach one as you would any policy, for example with
[DetachUserPolicy](/orgs-api/policies/DetachUserPolicy/). See [Attach a policy](/iam/policies#attach-a-policy).

Source: https://docs.ezghcloud.com/organizations/create-a-project/index.mdx
