An Elasticsearch API key is more than a bearer credential with index names attached. It represents a principal and a set of role descriptors, and its effective authority depends on the user who created or granted it. That makes key lifecycle, owner auditing, and document-level restrictions part of the same authorization review.
The API key service can create user API keys and cross-cluster API keys. The request can include role descriptors for indices and cluster privileges, expiration, and metadata. The key should be limited to the APIs and resources it needs. A key with a broad role because it was created by a highly privileged user can expose data that the service using the key was never meant to read.
Review the owner and the descriptors
Start with the creating user or service account. Record its roles and the reason it is allowed to grant the requested privileges. The key's role descriptors define its intended scope, but the policy should also account for the owner's authority. A key that appears limited can still be risky if its owner holds broad cluster privileges and can approve or create another key.
Use distinct keys for scheduled jobs, dashboards, ingestion, and administrative automation. Do not share one key across teams. Put purpose and owner in metadata so that the key can be found during an incident. Set an expiration for temporary automation and reissue the key after the task. Keep long-lived keys to an absolute minimum and put them in a secret manager rather than a source-controlled configuration file.
A key can be invalidated independently. Build a response procedure that identifies the credential, revokes it, rotates dependent jobs, and checks for use after revocation. The audit trail should include key creation, privilege changes, owner changes, and invalidation. If a key is embedded in a container image, deleting the key from the current environment does not remove it from old images or caches.
Apply document and field restrictions deliberately
Document-level security and field-level security restrict which documents and fields a role can see. They are useful when a shared index contains multiple tenants or when a support role should see case metadata but not personal data. The restrictions interact with multiple roles. A user or key with another role may receive broader access, so evaluate the combined result rather than one role in isolation.
Test the effective query result with the key itself. A search that returns the expected tenant does not prove that an aggregation, field, alias, or cross-cluster request enforces the same restriction. Check terms aggregations, wildcard queries, scroll or point-in-time access where supported, and error messages that could reveal whether a restricted document exists.
Field-level restrictions depend on a query model that applies to all relevant APIs. An index operation, update, bulk request, or scripted query may have different privilege requirements. A key intended only for search should not hold index-management or scripting privileges. Separate data ingestion from interactive search so a compromised dashboard key cannot rewrite the corpus.
Make key issuance observable
Centralize approval for keys that can read regulated data or change security settings. Store the business purpose, owner, expiration, and expected source network. Alert when a key with broad privileges is created outside the approved workflow. Alert on use from a new service, region, or user agent when the logging pipeline can capture those fields without exposing the key.
Do not log the API key value. Authentication logs should use a key ID or metadata label. If a request contains a key in a URL or query string, fix the client so the credential travels in the header and does not enter proxy logs. Review error responses and dashboards for accidental token exposure.
Build a rotation test. Create a short-lived key, use it for the intended API, then invalidate it and confirm that the next request fails. Revoke the owner's access and verify whether existing keys continue to work according to the product's documented behavior and the deployment's policy. Test a tenant query with both a narrow key and a broader administrative key to show where the boundary really sits.
Elasticsearch API keys are compact, which makes them easy to distribute and easy to forget. Treat each key as a named principal with an owner, scope, expiry, and review date. The privilege list matters, and so does the human or service identity that stands behind it.