cloud-access-management

What this skill does

# Cloud Access Management

Manage identity and access for an Elastic Cloud organization and its Serverless projects: invite users, assign
predefined or custom roles, and manage Cloud API keys.

> **Prerequisite:** This skill assumes the **cloud-setup** skill has already run — `EC_API_KEY` is set in the
> environment and the organization context is established. If `EC_API_KEY` is missing, instruct the agent to invoke
> **cloud-setup** first. Do NOT prompt the user for an API key directly.

For project creation, see the **cloud-create-project** skill. For day-2 project operations (list, update, delete), see
**cloud-manage-project**. For Elasticsearch-level role management (native users, role mappings, DLS/FLS), see the
**elasticsearch-authz** skill.

For detailed API endpoints and request schemas, see [references/api-reference.md](references/api-reference.md).

## Jobs to Be Done

- Invite a user to the organization and assign them a Serverless project role
- List organization members and their current role assignments
- Update a user's roles (org-level or project-level)
- Remove a user from the organization
- Create an additional Cloud API key with scoped roles and expiration
- Create a Cloud API key that can also call Elasticsearch and Kibana APIs on Serverless projects
- List and revoke Cloud API keys
- Create a custom role inside a Serverless project with ES cluster, index, and Kibana privileges
- Assign or remove a custom role for a user on a Serverless project using the Cloud API's `application_roles`
- Translate a natural-language access request into invite, role, and API key tasks

## Prerequisites and permissions

| Item                 | Description                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| **EC_API_KEY**       | Cloud API key (set by **cloud-setup**). Required for all operations.                                    |
| **Organization ID**  | Auto-discovered using `GET /organizations`. Do not ask the user for it.                                 |
| **Project endpoint** | Elasticsearch endpoint of a Serverless project. Required only for custom role operations.               |
| **ES credentials**   | API key or credentials with `manage_security` privilege on the project. Required only for custom roles. |
| **Org owner role**   | Only Organization owners can create and manage Cloud API keys. Required for API key operations.         |

Run `python3 skills/cloud/access-management/scripts/cloud_access.py list-members` to verify that `EC_API_KEY` is valid
and auto-discover the org ID before proceeding with any operation.

### Operation-level permissions

The following permissions are required for common access management operations in Elastic Cloud Serverless.

| Operation                          | Required permission                                            |
| ---------------------------------- | -------------------------------------------------------------- |
| Invite / remove members            | Organization owner (`organization-admin`)                      |
| Assign or remove roles             | Organization owner (`organization-admin`)                      |
| Create / revoke Cloud API keys     | Organization owner (`organization-admin`)                      |
| List members, invitations, or keys | Any organization member                                        |
| Create / delete custom roles       | `manage_security` cluster privilege on the project ES endpoint |

This skill does not perform a separate role pre-check. Attempt the requested operation and let the API enforce
authorization. If the API returns an authorization error (for example, `403 Forbidden`), stop and ask the user to verify
the provided API key permissions.

### Manual setup fallback (when cloud-setup is unavailable)

If this skill is installed standalone and `cloud-setup` is not available, instruct the user to configure Cloud
environment variables manually before running commands. Never ask the user to paste API keys in chat.

| Variable                | Required    | Description                                                                                       |
| ----------------------- | ----------- | ------------------------------------------------------------------------------------------------- |
| `EC_API_KEY`            | Yes         | Elastic Cloud API key with Organization owner role.                                               |
| `EC_BASE_URL`           | No          | Cloud API base URL (default: `https://api.elastic-cloud.com`).                                    |
| `ELASTICSEARCH_URL`     | Conditional | Elasticsearch URL. Required only for custom role operations.                                      |
| `ELASTICSEARCH_API_KEY` | Conditional | Elasticsearch API key with `manage_security` privilege. Required only for custom role operations. |

> **Note:** If `EC_API_KEY` is missing, or the user does not have a Cloud API key yet, direct the user to generate one
> at [Elastic Cloud API keys](https://cloud.elastic.co/account/keys), then configure it locally using the steps below.

Preferred method (agent-friendly): create a `.env` file in the project root:

```bash
EC_API_KEY=your-api-key
EC_BASE_URL=https://api.elastic-cloud.com
# Only needed for custom role operations against the project Elasticsearch endpoint:
# ELASTICSEARCH_URL=https://<project-id>.es.<region>.elastic-cloud.com
# ELASTICSEARCH_API_KEY=<your-es-manage-security-api-key>
```

All `cloud/*` scripts auto-load `.env` from the working directory.

Alternative: export directly in the terminal:

```bash
export EC_API_KEY="<your-cloud-api-key>"
export EC_BASE_URL="https://api.elastic-cloud.com"
# Only needed for custom role operations against the project Elasticsearch endpoint:
# export ELASTICSEARCH_URL="https://<project-id>.es.<region>.elastic-cloud.com"
# export ELASTICSEARCH_API_KEY="<your-es-manage-security-api-key>"
```

Terminal exports may not be visible to sandboxed agents running in separate shell sessions, so prefer `.env` when using
an agent.

## Decomposing Access Requests

When the user describes access in natural language (for example, "add Alice to my search project as a developer"), break
the request into discrete tasks before executing.

### Step 1 — Identify the components

| Component        | Question to answer                                                  |
| ---------------- | ------------------------------------------------------------------- |
| **Who**          | New org member (invite) or existing member (role update)?           |
| **What**         | Which Serverless project(s) or org-level access?                    |
| **Access level** | Predefined role (Admin/Developer/Viewer/Editor) or custom role?     |
| **API key?**     | Does the request also need a Cloud API key for programmatic access? |

### Step 2 — Check if a predefined role fits

Consult the [predefined roles table](#predefined-roles) below. Prefer predefined roles — only create a custom role when
predefined roles do not provide the required granularity.

### Step 3 — Check existing state

Before creating or inviting, check what already exists:

```bash
python3 skills/cloud/access-management/scripts/cloud_access.py list-members
python3 skills/cloud/access-management/scripts/cloud_access.py list-api-keys
```

If the user is already a member, skip the invitation and update their roles instead.

**For API key requests**, only Organization owners can create and manage Cloud API keys. If the authenticated user does
not have the `organization-admin` role, API key operations will fail with a 403 error. Review the existing keys returned
by `list-api-keys`. If an active key already exists **for the same purpose or task** with the required roles and
sufficient remaining lifetime, reuse it instead of creating a new one. Two