---
question: How do I give a person or a group access at a workspace, an organization or the platform?
kind: task
via_web: available
via_cli: na
via_python: na
via_api: available
via_config: na
ref_web: Roles & permissions › People & roles
ref_api: POST /api/iam/admin/attachments
prereq: You are an owner or admin of the workspace or organization, or the platform admin. You can give only what you hold there.
next:
  - /capabilities/platform/create-a-policy
  - /capabilities/platform/test-access-with-the-simulator
  - /capabilities/platform/view-as-another-person
---

# Give someone access

Access is a policy attached to a person or a group at a level. A role (viewer, member, admin) is a membership: you change it on the person's row. Anything else, such as a feature or a module's agent, is a policy you attach. In both cases IAM checks that you hold what you give.

## Web UI

### Open Roles & permissions at the level

Open the page where the access should apply:

- a workspace: the dock's **Settings**, then **Roles & permissions**;
- an organization: the account menu, **Organization Settings**, then **Roles & permissions**. Use **Manage** to switch to one of its workspaces;
- the platform: the account menu, **Platform Settings**, then **Roles & permissions** under Access.

Open **People & roles**. The table lists **Who**, their **Role**, the **Policies here** attached to them directly, and what reaches them **Through groups**.

### Change a role

On the person's row, pick a new **Role**: Viewer, Member or Admin at a workspace, Member or Admin at an organization. IAM attaches the role and the platform policies that come with it ("With the role: …"), and removes the old one.

Some roles are read-only here:

- an owner's role: owners come from the configuration or an ownership transfer, and no role offered here is owner;
- your own role;
- a role marked **from organization**: the organization's owners and admins reach every workspace. Change it in Organization Settings.

### Attach a policy

Under the table, in the attach form:

1. Pick the **Policy**. The list holds only the policies you may attach at this level, starting with **Choose a policy**.
2. In **To**, pick a person or a group, or type an id: `usr_…`, `grp_…` or `sa_…`.
3. Choose **Attach policy**.

The policy now reaches that principal at this level. To give the same policy to many people, attach it to a group: see [Manage groups](/capabilities/platform/manage-groups).

### Or start from the person's page

Select a person's name to open their page. **Roles and policies, at every level** lists each role and policy they hold that you may see, where it is attached, and whether it is **Direct**, comes with a role, or comes through a group. **Attach a policy** attaches one to them; **At** picks the level when you may attach at several.

### Remove access

Select the **×** on a policy in **Policies here**, or **Detach** on a row of the person's page, then **Confirm detach**. A role and what comes with it are not detached here: change or remove the membership instead.

If IAM refuses, its message names what you do not hold, for example "You cannot grant what you do not hold: … allows module:UseAgent on …".

## CLI

Not applicable. `abi iam` has no command that attaches a policy or changes a role. To give a role to someone who has not signed in yet, use [`abi iam invite`](/user-guide/reference/cli#abi-iam-invite); to give a role to the members of an identity provider's group, see [Manage groups](/capabilities/platform/manage-groups?via=cli).

## Python

Not applicable. The SDK checks access for a module; it does not attach policies. Use the Web UI or the REST API.

## REST API

:::warning Session only
The routes under `/api/iam/admin/` take a signed-in session only. A personal API key (`abi_pk_…`) is refused with 403 on `/api/iam/`, so a script that holds one cannot attach policies. The role routes below take a personal API key.
:::

### Change a role

```bash
curl -X PATCH http://localhost:9879/api/workspaces/<ws-id>/members/<user-id> \
  -H "Authorization: Bearer $NEXUS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "member"}'
```

At an organization, the route is `PATCH /api/organizations/<org-id>/members/<user-id>`, with `member` or `admin`.

### Attach a policy

With the signed-in session:

```http
POST /api/iam/admin/attachments
Content-Type: application/json

{
  "policy_id": "pol_01jexample0000000000000000",
  "principal_id": "grp_01jexample0000000000000000",
  "scope": "abi:nexus:organization/<org>/nexus:workspace/<ws>"
}
```

`scope` is the level: `abi:nexus:organization/<org>` for an organization, `abi:nexus:organization/<org>/*` for an organization and every workspace in it, and none for the platform. `GET /api/iam/admin/attachable-policies?scope=` lists what you may attach there. A grant beyond what you hold is a 403 with IAM's message.

### Detach

```http
DELETE /api/iam/admin/attachments?policy_id=pol_…&principal_id=grp_…&scope=abi:nexus:organization/<org>/nexus:workspace/<ws>
```

## Config

Not applicable. Roles and policies are given in Nexus, not in `config.yaml`.
