# Grant access to one resource

Let a person, group or role do named things with one repository, app, database, hosted zone or secret, without writing a policy.

A grant gives one principal a set of **capabilities** on one named resource. The platform writes an
ordinary custom policy for it: one `Allow` statement with the capabilities' actions on that
resource's name, attached to the principal you chose. Replace org-EXAMPLE1234 with your
organization id, and the ids with your own.

## Capabilities

| Resource   | Capabilities (id)                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Repository | Read (`repository.read`), Push (`repository.push`), Administer (`repository.administer`)                                       |
| App        | View (`app.view`), Deploy (`app.deploy`), Manage environment (`app.manage-env`), Administer (`app.administer`)                 |
| Database   | View (`database.view`), Branches (`database.branch`), Connect and query (`database.query`), Administer (`database.administer`) |
| Zone       | View (`zone.view`), Change records (`zone.change-records`), Administer (`zone.administer`)                                     |
| Secret     | View (`secret.view`), Read the value (`secret.read-value`), Rotate (`secret.rotate`), Administer (`secret.administer`)         |

A stronger capability carries the weaker ones: Push includes Read, and Administer includes the
others of its resource, except on a database. There, Administer includes View but not Connect and
query or Branches: administering a database is not reading its data, so select both when you
mean both.

## Prerequisites

- To grant to a person or IAM user, `iam:AttachUserPolicy` on them; to a group,
  `iam:AttachGroupPolicy`; to a role, `iam:AttachRolePolicy`.
- You must be allowed every action you hand out, on that resource. Otherwise the grant is refused
  and names the action you lack.
- To take a grant back, the detach action for the principal (`iam:DetachUserPolicy`,
  `iam:DetachGroupPolicy` or `iam:DetachRolePolicy`) and `iam:DeletePolicy`.
- To list the grants on a resource, `iam:ListPolicies`. In the console the **Access** panel also
  needs `iam:ListUsers` to show who has access, and offers **Give someone access** only with
  `iam:AttachUserPolicy`, also for a group or a role.

## Make the grant

**Console**
1. Open the resource's **Access** panel, for example the **Access** tab of a database or a hosted
   zone.
2. Choose **Give someone access**.
3. Under **Who**, choose **Member or IAM user**, **Group** or **Role**, then choose who.
4. Under **What they may do**, select the capabilities.
5. Choose **Grant**. The grant appears in the panel's list.

**CLI**
```sh
dcloud iam grants create --principal '{"kind":"user","id":"user-id"}' \
  --resource 'rn:ews::org-EXAMPLE1234:git:repository/repo-id' \
  --capabilities repository.push
```

**API**
```http
POST /iam/api/grants
{ "principal": { "kind": "user", "id": "3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0f" }, "resource": "rn:ews::org-EXAMPLE1234:git:repository/9b2e4c1a-7d3f-4e8a-b6c5-0a1b2c3d4e5f", "capabilities": ["repository.push"] }
```

**Terraform**
```hcl
resource "dcloud_iam_grant" "alice_pushes" {
  principal_kind = "user"
  principal_id   = dcloud_iam_user.alice.id
  resource       = "rn:ews::${var.org_id}:git:repository/${dcloud_git_repository.app.id}"
  capabilities   = ["repository.push"]
}
```

## Result

The principal may do what the capabilities say on that one resource, from their next request on.
The policy is listed under **Identity** → **Policies**, named after the capabilities and the
resource. The grant also appears on the principal's **Permissions** tab under
**Access on resources**.

`dcloud iam grants list --resource …` (or `GET /iam/api/grants?resource=…`) lists the grants on a
resource. It lists only policies written by a grant; a policy you wrote by hand that mentions the
same resource is not a grant.

## Take a grant back

On the resource's **Access** panel, choose **Take back** on the grant's row; it is taken back at
once. Under **Access on resources** on the principal's **Permissions** tab, choose **Take back** and
confirm with **Take back**. With the CLI: `dcloud iam grants revoke <policy id>`.
Taking back detaches the policy from whoever holds it and deletes it.

## If the grant is refused

- 403 `You cannot grant … on this resource, because you are not allowed to do it yourself`:
  the message names the action you lack.
- 400 `That resource name is not one of this organization’s resources`.
- 400 `A capability is given on one named resource, not on a wildcard. Write a wider permission on the policy pages, where it says so`.
- 400 `There is no capability called "…"`, or `“Push” applies to a repository, not to a …`.
- 404 `That user was not found` (or group, role).
- 409 `Quota exceeded: …`: a grant is a custom policy and counts toward the organization's
  policies; see [Quotas](quotas.md).
- When taking back a policy you wrote by hand: 400
  `That policy was not created by the Access panel. Detach or delete it from the policy page`.

## Related

- [Attach a policy](attach-a-policy.md)
- [Test access with the policy simulator](test-access-with-the-simulator.md)
- `iam.grants.create` · `dcloud iam grants create` · `dcloud_iam_grant`
