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.
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, then configure it locally using the steps below.
Preferred method (agent-friendly): create a .env file in the project root:
EC_API_KEY=your-api-key
EC_BASE_URL=https://api.elastic-cloud.com
All cloud/* scripts auto-load .env from the working directory.
Alternative: export directly in the terminal:
export EC_API_KEY="<your-cloud-api-key>"
export EC_BASE_URL="https://api.elastic-cloud.com"
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 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:
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 keys with identical permissions are fine when
they serve different purposes (for example, separate CI pipelines), but creating a second key for the same task is
unnecessary and increases the management burden.
Step 4 — Run
Run the appropriate command(s) from skills/cloud/access-management/scripts/cloud_access.py. Confirm destructive
actions (remove member, revoke key) with the user before executing.
Step 5 — Verify
After execution, list members or keys again to confirm the change took effect.
Predefined Roles
Organization-level roles
| Role |
Cloud API role_id |
Description |
| Organization owner |
organization-admin |
Full admin over org, deployments, projects |
| Billing admin |
billing-admin |
Manage billing details only |
Serverless project-level roles
| Role |
Cloud API role_id |
Available on |
Description |
| Admin |
admin |
Search, Obs, Security |
Full project management, superuser on sign-in |
| Developer |
developer |
Search only |
Create indices, API keys, connectors, visualizations |
| Viewer |
viewer |
Search, Obs, Security |
Read-only access to project data and features |
| Editor |
editor |
Obs, Security |
Configure project features, read-only data indices |
| Tier 1 analyst |
t1_analyst |
Security only |
Alert triage, general read, create dashboards |
| Tier 2 analyst |
t2_analyst |
Security only |
Alert triage, begin investigations, create cases |
| Tier 3 analyst |
t3_analyst |
Security only |
Deep investigation, rules, lists, response actions |
| SOC manager |
soc_manager |
Security only |
Alerts, cases, endpoint policy, response actions |
| Rule author |
rule_author |
Security only |
Detection engineering, rule creation |
Project-level roles are assigned during invitation (POST /organizations/{org_id}/invitations) or using the role
assignment update (POST /users/{user_id}/role_assignments). See
references/api-reference.md for the role_assignments JSON schema including the
project scope.
Custom Roles (Serverless)
When predefined roles lack the required granularity, create a custom role inside the Serverless project using the
Elasticsearch security API and assign it to users through the Cloud API's application_roles field.
Security: do not assign a predefined Cloud role separately when using a custom role. Custom roles implicitly grant
Viewer-level Cloud access for the project scope. If you also assign viewer (or any other predefined role) as a
separate Cloud role assignment for the same project, the user receives the union of both roles when they SSO into
the project — the Viewer stack role is broader than most custom roles and will override the restrictions you intended.
How custom role assignment works
- Predefined roles (
viewer, developer, admin, etc.) are assigned via Cloud APIs (invite-user,
assign-role). When the user SSOs into the project, they receive the stack role mapped to their Cloud role (for
example, Cloud viewer maps to the viewer stack role).
- Custom roles are created in the project via the Elasticsearch security API (
create-custom-role) and assigned via
the Cloud API's application_roles field (assign-custom-role). When application_roles is set, the user gets
only the specified custom role on SSO — not the default stack role for their Cloud role.
- The
assign-custom-role command sets role_id to the project-type Viewer role (elasticsearch-viewer,
observability-viewer, or security-viewer) and sets application_roles to the custom role name. This ensures the
user can see and access the project in the Cloud console but receives only the custom role's restricted permissions
inside the project.
- Cloud API keys can also use
application_roles to gain ES/Kibana API access on Serverless projects. See
Cloud API Keys — ES and Kibana API Access below for details.
Canonical custom-role onboarding flow
- Create the custom role in the project (
create-custom-role).
- Invite the user to the organization if they are not already a member (
invite-user). Do not include project role
assignments in the invitation — the custom role assignment in the next step handles project access.
- Assign the custom role to the user (
assign-custom-role --user-id ... --project-id ... --custom-role-name ...).
- Verify with
list-members and list-roles.
Create a custom role
python3 skills/cloud/access-management/scripts/cloud_access.py create-custom-role \
--role-name marketing-analyst \
--body '{"cluster":[],"indices":[{"names":["marketing-*"],"privileges":["read","view_index_metadata"]}]}'
This calls PUT /_security/role/{name} on the project Elasticsearch endpoint.
Naming constraints
Role names must begin with a letter or digit and contain only letters, digits, _, -, and .. Run-as privileges are
not available in Serverless.
When to use custom roles versus predefined
| Scenario |
Use |
| Standard admin/developer/viewer access |
Predefined role |
| Read-only access to specific index pattern |
Custom role |
| DLS or FLS restrictions |
Custom role |
| Kibana feature-level access control |
Custom role |
For advanced DLS/FLS patterns (templated queries, ABAC), see the elasticsearch-authz skill.
Cloud API Keys — ES and Kibana API Access
Cloud API keys can now optionally access Elasticsearch and Kibana APIs on Serverless projects, in addition to the Cloud
API. This enables a single credential for both control plane (Cloud API) and data plane (ES/Kibana API) operations — for
example, a CI pipeline that creates a project via Cloud API and then indexes data via ES API.
How it works
Add application_roles to the key's role_assignments at creation time. This field accepts an array of predefined role
names (admin, developer, viewer, and solution-specific roles like t1_analyst, editor) or custom role names
created in the project via PUT /_security/role/{name}. Predefined roles are available in every project by default.
Custom roles must be created individually in each project where the key should have access — if a referenced custom role
does not exist in a project, the key silently gets no access there.
Critical rule: no implicit inheritance
Unlike users, API keys never inherit stack roles from their role_id. If application_roles is omitted or empty,
the key has Cloud API access only. Calling an ES or Kibana endpoint with such a key returns 403 Forbidden. This is
by design for backward compatibility — existing keys without application_roles continue to work as Cloud-only keys.
Scoping modes
-
Project-scoped (preferred) — grants access to specific projects or all projects of a given type. Uses the
project key in role_assignments with application_roles on each entry. Use this by default unless the user
explicitly needs cross-project access.
-
Organization-scoped — grants access to all current and future projects in the organization. Uses the
organization key in role_assignments with application_roles. This is the broadest possible data-plane scope.
Only use when the key genuinely needs access to every project (for example, platform automation or cross-project
search across the whole org). Always confirm with the user before creating an org-scoped key with application_roles,
as it grants ES/Kibana access to projects that may not exist yet.
Custom roles and org-scoped access: When using a custom role name in application_roles with organization-scoped
assignments, the custom role must exist in each project where you want the key to have access. If a project does not
have that custom role defined (via PUT /_security/role/{name}), the key silently gets no access to that project — no
error is raised. For org-wide access, prefer predefined roles (admin, developer, viewer) which are available in
every project by default. If you must use custom roles across multiple projects, ensure the role is created in each
target project first.
Agent guidance: When a user asks for an API key with ES/Kibana access, default to project-scoped assignments. Only
suggest organization-scoped application_roles if the user explicitly needs access across all projects. Confirm the
intent before proceeding — org-scoped access applies to future projects too. If the user specifies a custom role name
with org-scoped access, warn them that the role must be defined in each project individually.
Examples
Project-scoped key with developer ES access (using --stack-access convenience flag):
python3 skills/cloud/access-management/scripts/cloud_access.py create-api-key \
--description "CI pipeline - ES ingest" \
--expiration 30d \
--roles '{"project":{"elasticsearch":[{"role_id":"developer","organization_id":"$ORG_ID","all":true}]}}' \
--stack-access developer
Organization-scoped key with admin ES access (access to ALL projects — use with caution):
python3 skills/cloud/access-management/scripts/cloud_access.py create-api-key \
--description "Platform automation" \
--expiration 7d \
--roles '{"organization":[{"role_id":"organization-admin","organization_id":"$ORG_ID"}]}' \
--stack-access admin
Project-scoped key with a custom role (raw JSON):
python3 skills/cloud/access-management/scripts/cloud_access.py create-api-key \
--description "Marketing ETL" \
--expiration 14d \
--roles '{"project":{"elasticsearch":[{"role_id":"elasticsearch-viewer","organization_id":"$ORG_ID","all":false,"project_ids":["$PROJECT_ID"],"application_roles":["marketing-writer"]}]}}'
Replace $ORG_ID and $PROJECT_ID w
