Cloud Access Management

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

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.

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.

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
# 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:

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

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

Serverless project-level roles

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

1. Create the custom role in the project (create-custom-role). 2. 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. 3. Assign the custom role to the user (assign-custom-role --user-id ... --project-id ... --custom-role-name ...). 4. 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

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 with the actual organization and project IDs. Use list-members to discover the org ID.

Common mistake: If your API key gets a 403 when calling an ES or Kibana endpoint, the most likely cause is missing

application_roles. Unlike users, API keys must have explicit application_roles to access the stack — the role_id

alone is not sufficient.

Examples

Invite a user as a Viewer on a search project

Prompt: "Add alice@example.com to my search project with read-only access."

python3 skills/cloud/access-management/scripts/cloud_access.py invite-user \
  --emails alice@example.com \
  --roles '{"project":{"elasticsearch":[{"role_id":"viewer","organization_id":"$ORG_ID","all":false,"project_ids":["$PROJECT_ID"]}]}}'

Replace $ORG_ID and $PROJECT_ID with the actual IDs. The Viewer role is assigned when the invitation is accepted. For custom role access, use assign-custom-role after the user has accepted the invitation — do not combine a predefined role assignment with a custom role for the same project.

Create a CI/CD API key

Prompt: "Create an API key for our CI pipeline that expires in 30 days with editor access to all deployments."

python3 skills/cloud/access-management/scripts/cloud_access.py create-api-key \
  --description "CI/CD pipeline" \
  --expiration "30d" \
  --roles '{"deployment":[{"role_id":"deployment-editor","all":true}]}'

The actual key value is written to a secure temp file (0600 permissions). The stdout JSON contains a _secret_file path instead of the raw secret. Tell the user to retrieve the key from that file — it is shown only once. When the CI pipeline no longer needs this key, revoke it using delete-api-key to avoid unused keys accumulating.

Create a CI/CD API key with ES access

Prompt: "Create an API key for our CI pipeline that can index data into our search projects."

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

Replace $ORG_ID with the actual organization ID. The --stack-access flag injects application_roles: ["developer"] into the role assignments, granting the key developer-level ES/Kibana API access on all Elasticsearch projects. Without --stack-access (or explicit application_roles in the JSON), the key would only have Cloud API access and receive 403 on ES/Kibana calls.

Create a custom role for marketing data

Prompt: "Create a role that gives read-only access to marketing-\* indices on my search project."

python3 skills/cloud/access-management/scripts/cloud_access.py create-custom-role \
  --role-name marketing-reader \
  --body '{"cluster":[],"indices":[{"names":["marketing-*"],"privileges":["read","view_index_metadata"]}]}'

Then assign the custom role to a user using the assign-custom-role command, which sets application_roles in the Cloud API role assignment.

Full custom-role flow for read-only dashboards

Prompt: "Add bob@example.com to my search project with read-only dashboard access."

# 1) Create custom role in the project
python3 skills/cloud/access-management/scripts/cloud_access.py create-custom-role \
  --role-name dashboard-reader \
  --body '{"cluster":[],"indices":[],"applications":[{"application":"kibana-.kibana","privileges":["feature_dashboard.read"],"resources":["*"]}]}'

# 2) Invite user to the organization (no project roles — custom role handles access)
python3 skills/cloud/access-management/scripts/cloud_access.py invite-user \
  --emails bob@example.com

# 3) After invitation is accepted, assign the custom role via application_roles
python3 skills/cloud/access-management/scripts/cloud_access.py assign-custom-role \
  --user-id "$USER_ID" \
  --project-id "$PROJECT_ID" \
  --project-type elasticsearch \
  --custom-role-name dashboard-reader

The user receives Viewer-level Cloud access (can see the project in the console) and only dashboard-reader permissions when they SSO into the project. Do not also assign viewer as a separate Cloud role for this project — doing so would grant the broader Viewer stack role and override the custom role's restrictions.

Update a user's project role

Prompt: "Promote Bob to admin on our observability project."

python3 skills/cloud/access-management/scripts/cloud_access.py assign-role \
  --user-id "$USER_ID" \
  --roles '{"project":{"observability":[{"role_id":"admin","organization_id":"$ORG_ID","all":false,"project_ids":["$PROJECT_ID"]}]}}'

Replace $USER_ID, $ORG_ID, and $PROJECT_ID with actual values. Use list-members to look up the user ID. To remove a role assignment, use remove-role-assignment with the same --roles schema.

List all members and their roles

Prompt: "Show me who has access to my organization."

python3 skills/cloud/access-management/scripts/cloud_access.py list-members

The output includes each member's user ID, email, and assigned roles.

Guidelines

• If EC_API_KEY is not set, do not prompt the user — instruct the agent to invoke cloud-setup first.
• Always confirm destructive actions (remove member, revoke key) with the user before executing.
• Prefer predefined roles over custom roles when they satisfy the access requirement.
• API keys created here are additional keys for CI/CD, scoped access, or team members. The initial key is managed by

cloud-setup.

• Secrets are never printed to stdout or stderr. The script replaces sensitive fields (key, token,

invitation_token) with a REDACTED placeholder in stdout and writes the full unredacted response to a temporary file with 0600 (owner-read-only) permissions. The stdout JSON includes a _secret_file path pointing to that file. Never attempt to read, extract, or summarize the contents of the secret file. If the user asks for the key, tell them to open the file at the _secret_file path. After the user retrieves the secret, advise them to delete the file.

• Cloud API keys inherit roles at creation and cannot be updated — revoke and recreate to change roles.
• API key hygiene — minimize, scope, and expire:
• Before creating a key, always run list-api-keys and check whether an existing key for the same purpose or task

already has the required roles and sufficient remaining lifetime. Keys with identical permissions serving different purposes (for example, two separate CI pipelines) are legitimate — the goal is to avoid redundant keys for the same task.

• Always set an --expiration that matches the intended task lifetime. Short-lived tasks (CI runs, one-time

migrations) should use short-lived keys (for example, 1d, 7d).

• After a task is complete, prompt the user to revoke any keys that are no longer needed using delete-api-key. This

applies to both short-lived and long-running keys.

• Long-running keys (for example, monitoring pipelines) should still have a defined expiration and be rotated

periodically rather than set to never expire.

• Each organization supports up to 500 active API keys. Default expiration is 3 months.
• Invitations expire after 72 hours by default. Resend if the user has not accepted.
• For SAML SSO configuration, refer to

Elastic Cloud SAML docs.

• Custom role security — do not over-assign: Never assign a predefined Cloud role (for example, viewer) for a

project when using assign-custom-role for the same project. The custom role assignment implicitly grants Viewer-level Cloud access. Adding a predefined role on top widens the user's in-project permissions beyond what the custom role intended.

• If a custom role exists but the user cannot access the project, verify the role was assigned with assign-custom-role

(which uses application_roles in the Cloud API). Creating a custom role alone does not grant project access — the Cloud API assignment is required.

• For network-level security (traffic filters, private links), see the cloud-network-security skill.
• For ES-level role management beyond Cloud roles (native users, DLS/FLS), see elasticsearch-authz.

Cloud Access Management — API Reference

All Cloud API calls use base URL https://api.elastic-cloud.com/api/v1 and require the header Authorization: ApiKey $EC_API_KEY.

Serverless ES API calls use the project Elasticsearch endpoint and require either basic auth or an Elasticsearch API key with manage_security privileges.

Table of Contents

• Organization Discovery
• Organization Members
• List members
• Invite users
• List pending invitations
• Cancel invitations
• Remove members
• Role Assignments
• Add role assignments to a user
• Role assignments schema
• Assign a custom role using application_roles
• Remove role assignments
• Cloud API Keys
• Create an API key
• List all API keys
• Delete API keys
• Serverless Custom Roles (Elasticsearch Security API)
• Create or update a custom role
• Get a custom role
• List all roles
• Delete a custom role

---

Organization Discovery

Official API docs:

List organizations

Get organizations

GET /organizations

Returns the list of organizations the authenticated user belongs to. Use to auto-discover organization_id.

curl -s -H "Authorization: ApiKey $EC_API_KEY" \
  "https://api.elastic-cloud.com/api/v1/organizations"

Response (200):

{
  "organizations": [
    {
      "id": "org-uuid-here",
      "name": "My Organization"
    }
  ]
}

---

Organization Members

Official API docs:

List members ·

Invite users ·

List invitations ·

Delete invitations ·

Remove members

List members

GET /organizations/{organization_id}/members

curl -s -H "Authorization: ApiKey $EC_API_KEY" \
  "https://api.elastic-cloud.com/api/v1/organizations/$ORG_ID/members"

Response (200):

{
  "members": [
    {
      "user_id": "user-uuid",
      "email": "alice@example.com",
      "name": "Alice",
      "role_assignments": { ... }
    }
  ]
}

Invite users

POST /organizations/{organization_id}/invitations

curl -s -X POST \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.elastic-cloud.com/api/v1/organizations/$ORG_ID/invitations" \
  -d '{
    "emails": ["alice@example.com", "bob@example.com"],
    "expires_in": "3d",
    "role_assignments": {
      "organization": [
        { "role_id": "billing-admin" }
      ],
      "deployment": [
        {
          "role_id": "deployment-viewer",
          "organization_id": "'"$ORG_ID"'",
          "all": true
        }
      ]
    }
  }'

Request body fields:

Cloud invitation payloads support Cloud role assignments including application_roles for custom roles. However, the recommended flow is to invite the user first (without project roles) and then assign the custom role separately using assign-custom-role after the invitation is accepted. This avoids accidentally combining a predefined role with a custom role for the same project.

List pending invitations

GET /organizations/{organization_id}/invitations

curl -s -H "Authorization: ApiKey $EC_API_KEY" \
  "https://api.elastic-cloud.com/api/v1/organizations/$ORG_ID/invitations"

Cancel invitations

DELETE /organizations/{organization_id}/invitations/{invitation_tokens}

invitation_tokens is a comma-separated list of invitation token strings.

curl -s -X DELETE -H "Authorization: ApiKey $EC_API_KEY" \
  "https://api.elastic-cloud.com/api/v1/organizations/$ORG_ID/invitations/$TOKEN"

Remove members

DELETE /organizations/{organization_id}/members/{user_ids}

user_ids is a comma-separated list of user IDs.

curl -s -X DELETE -H "Authorization: ApiKey $EC_API_KEY" \
  "https://api.elastic-cloud.com/api/v1/organizations/$ORG_ID/members/$USER_ID"

---

Role Assignments

Official API docs:

Add role assignments ·

Remove role assignments

Add role assignments to a user

POST /users/{user_id}/role_assignments

curl -s -X POST \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.elastic-cloud.com/api/v1/users/$USER_ID/role_assignments" \
  -d '{
    "organization": [
      { "role_id": "organization-admin" }
    ],
    "deployment": [
      {
        "role_id": "deployment-editor",
        "organization_id": "'"$ORG_ID"'",
        "all": true
      }
    ],
    "project": {
      "elasticsearch": [
        {
          "role_id": "admin",
          "organization_id": "'"$ORG_ID"'",
          "all": false,
          "project_ids": ["project-uuid-here"]
        }
      ],
      "observability": [],
      "security": []
    }
  }'

Role assignments schema

{
  "organization": [
    {
      "role_id": "<org-role-id>",
      "organization_id": "<org-id>",
      "application_roles": ["<predefined-or-custom-role>"]
    }
  ],
  "deployment": [
    {
      "role_id": "<deployment-role-id>",
      "organization_id": "<org-id>",
      "all": true,
      "deployment_ids": []
    }
  ],
  "project": {
    "elasticsearch": [
      {
        "role_id": "<project-role-id>",
        "organization_id": "<org-id>",
        "all": false,
        "project_ids": ["<project-id>"],
        "application_roles": ["<custom-role-name>"]
      }
    ],
    "observability": [],
    "security": []
  }
}

Organization role IDs: organization-admin, billing-admin

Deployment role IDs: deployment-admin, deployment-editor, deployment-viewer

Serverless project role IDs (Elasticsearch): admin, developer, viewer

Serverless project role IDs (Observability): admin, editor, viewer

Serverless project role IDs (Security): admin, editor, viewer, t1_analyst, t2_analyst, t3_analyst, threat_intel_analyst, rule_author, soc_manager, endpoint_operations_analyst, platform_engineer, detections_admin, endpoint_policy_manager

For project-scoped assignments that include application_roles, use project-type-specific viewer role IDs: elasticsearch-viewer, observability-viewer, security-viewer (not the generic viewer).

`application_roles` (optional, array of strings): Specifies which ES/Kibana roles to grant. Accepts predefined role names (admin, developer, viewer, and solution-specific roles) or custom role names created in the project via PUT /_security/role/{name}. Serverless only. Behavior depends on the principal type:

• For users: When set on a project-scoped assignment, the user receives these roles when signing into the project

instead of the default stack role mapped to role_id.

• For API keys: Grants ES/Kibana API access. Unlike users, API keys never inherit stack roles from role_id —

application_roles must be explicitly provided. If omitted or empty, the API key has Cloud API access only and receives 403 Forbidden when calling ES/Kibana endpoints.

• On organization scope: Grants the specified roles across all projects (current and future) in the

organization. Supported for API keys.

Broad access warning: Organization-scoped application_roles is the broadest possible data-plane scope — it

grants ES/Kibana access to every project in the organization, including projects created after the key. Use

project-scoped assignments when the key only needs access to specific projects. Reserve org-scoped application_roles

for platform automation keys that genuinely require cross-project access.

>

Custom roles with org scope: When using a custom role name in application_roles, the role must be defined in

each project where the key should have access (via PUT /_security/role/{name}). If a project does not have that

role, the key silently gets no access there — no error is raised. Predefined roles (admin, developer, viewer)

are available in every project by default and do not have this limitation.

Security: When using application_roles, the user automatically receives Viewer-level Cloud access for the

project. Do not also assign a predefined Cloud role (such as viewer) for the same project as a separate role

assignment — the user would receive the union of both roles on sign-in, which is broader than the custom role intends.

Assign a custom role using application_roles

curl -s -X POST \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.elastic-cloud.com/api/v1/users/$USER_ID/role_assignments" \
  -d '{
    "project": {
      "elasticsearch": [
        {
          "role_id": "elasticsearch-viewer",
          "organization_id": "'"$ORG_ID"'",
          "all": false,
          "project_ids": ["'"$PROJECT_ID"'"],
          "application_roles": ["marketing-reader"]
        }
      ]
    }
  }'

This grants the user Viewer-level Cloud access (project visible in the console) and only the marketing-reader custom role when they SSO into the project — not the full Viewer stack role. Use the project-type-specific Viewer role ID (elasticsearch-viewer, observability-viewer, or security-viewer) for the role_id value.

Remove role assignments

DELETE /users/{user_id}/role_assignments

Uses the same body schema as POST. Removes the specified role assignments from the user.

---

Cloud API Keys

Official API docs: Create API key

· List API keys ·

Delete API keys

Only Organization owners (organization-admin role) can create and manage Cloud API keys. Non-owner requests return 403.

Create an API key

POST /users/auth/keys

curl -s -X POST \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.elastic-cloud.com/api/v1/users/auth/keys" \
  -d '{
    "description": "CI/CD pipeline key",
    "expiration": "30d",
    "role_assignments": {
      "organization": [
        { "role_id": "billing-admin" }
      ],
      "deployment": [
        {
          "role_id": "deployment-editor",
          "organization_id": "'"$ORG_ID"'",
          "all": true
        }
      ]
    }
  }'

Project-scoped API key with ES access (grants developer access to all Elasticsearch projects):

curl -s -X POST \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.elastic-cloud.com/api/v1/users/auth/keys" \
  -d '{
    "description": "CI pipeline with ES access",
    "expiration": "30d",
    "role_assignments": {
      "project": {
        "elasticsearch": [
          {
            "role_id": "developer",
            "organization_id": "'"$ORG_ID"'",
            "all": true,
            "application_roles": ["developer"]
          }
        ]
      }
    }
  }'

Organization-scoped API key with ES access (grants admin access to ALL current and future projects):

curl -s -X POST \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.elastic-cloud.com/api/v1/users/auth/keys" \
  -d '{
    "description": "Platform automation key",
    "expiration": "7d",
    "role_assignments": {
      "organization": [
        {
          "role_id": "organization-admin",
          "organization_id": "'"$ORG_ID"'",
          "application_roles": ["admin"]
        }
      ]
    }
  }'

Caution: This grants admin-level ES/Kibana access to every project in the organization, including projects created

after the key. Use project-scoped assignments for narrower access.

Request body fields:

403 on ES/Kibana calls: If an API key without application_roles calls an Elasticsearch or Kibana endpoint, the

request returns 403 Forbidden. Unlike users, API keys never inherit stack roles from role_id. Add explicit

application_roles when the key needs data-plane access.

Response (201):

{
  "id": "key-uuid",
  "key": "the-actual-api-key-value",
  "description": "CI/CD pipeline key",
  "creation_date": "2026-02-27T10:00:00Z",
  "expiration_date": "2026-03-29T10:00:00Z",
  "organization_id": "org-uuid",
  "user_id": "user-uuid",
  "role_assignments": { ... }
}

The key field is returned only once at creation. Store it securely.

List all API keys

GET /users/auth/keys

curl -s -H "Authorization: ApiKey $EC_API_KEY" \
  "https://api.elastic-cloud.com/api/v1/users/auth/keys"

Delete API keys

DELETE /users/auth/keys

curl -s -X DELETE \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.elastic-cloud.com/api/v1/users/auth/keys" \
  -d '{"keys": ["key-id-1", "key-id-2"]}'

---

Serverless Custom Roles (Elasticsearch Security API)

Official API docs:

Create/update role ·

Get role ·

Delete role

These endpoints run against the project Elasticsearch endpoint, not the Cloud API. They require an Elasticsearch API key or credentials with manage_security cluster privilege.

Create or update a custom role

PUT /_security/role/{name}

curl -s -X PUT \
  -H "Authorization: ApiKey $ELASTICSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  "$ELASTICSEARCH_URL/_security/role/marketing-analyst" \
  -d '{
    "cluster": [],
    "indices": [
      {
        "names": ["marketing-*"],
        "privileges": ["read", "view_index_metadata"]
      }
    ],
    "applications": [
      {
        "application": "kibana-.kibana",
        "privileges": ["feature_discover.read", "feature_dashboard.read"],
        "resources": ["*"]
      }
    ]
  }'

Request body fields:

Naming rules: Must start with a letter or digit. Only letters, digits, _, -, . are allowed.

Limitation: Run-as privileges are not available in Serverless.

Get a custom role

GET /_security/role/{name}

curl -s -H "Authorization: ApiKey $ELASTICSEARCH_API_KEY" \
  "$ELASTICSEARCH_URL/_security/role/marketing-analyst"

List all roles

GET /_security/role

curl -s -H "Authorization: ApiKey $ELASTICSEARCH_API_KEY" \
  "$ELASTICSEARCH_URL/_security/role"

Delete a custom role

DELETE /_security/role/{name}

curl -s -X DELETE -H "Authorization: ApiKey $ELASTICSEARCH_API_KEY" \
  "$ELASTICSEARCH_URL/_security/role/marketing-analyst"