Skip to main content
When the password, token, or key for a private registry changes, update the package manager integration so that scans keep resolving private dependencies. Use endorctl api update with a field mask to replace only the credential and leave the rest of the integration unchanged. Run the same command from your secret rotation job to rotate credentials on a schedule.

Before you begin

Make sure you have the following:
  • endorctl installed and authenticated to your tenant. See Install and configure endorctl to set it up.
  • The Admin role in the namespace. For an automated job, use an API key with the Admin role. See Authorization roles to compare what each role can access.
  • The new credential from your registry.

Credential fields by ecosystem

Each ecosystem stores its credential in a specific field. Use the field mask that matches the field your integration already uses. For Maven, PyPI, RubyGems, and NuGet, endorctl uses token_auth first, then basic_auth, then the legacy user and password fields. Update only the field that your integration already uses. Writing a different field can leave scans on the old credential or break authentication. AWS CodeArtifact integrations authenticate with an IAM role and store no secret, so they have nothing to rotate. mTLS client certificates rotate the same way. Use the mtls.client_cert and mtls.client_key fields of the ecosystem, such as spec.mvn.mtls.client_cert. See Authenticate to private packages using mTLS to learn which ecosystems support mTLS.

Rotate a credential with endorctl

Replace the stored credential with the new value from your registry.
  1. List the package manager integrations in your namespace. Replace <namespace> with your namespace.
    Stored credentials appear as <redacted>. The field that holds <redacted> is the field your integration uses. If more than one field shows <redacted>, the integration uses the first in this order: token_auth, basic_auth, then the legacy password.
    An npm integration can store both auth_token and token. When both show <redacted>, the integration uses auth_token.
  2. Note the uuid of the integration and find its field mask in the credential fields table.
  3. Update the credential. Replace <package-manager-uuid> with the UUID and <new-password> with the new credential. This example rotates the password of a Maven integration that uses basic_auth.
    For another field, change the --field-mask value and nest the new value under the same path in -d. The username and every field outside the mask stay as they are.
Always send the real credential, never <redacted>. Depending on the field, Endor Labs rejects the update, keeps the old credential, or stores the placeholder in place of your credential.

Rotate a Google Artifact Registry service account key

A service account key is a JSON document, so build the request body with jq to escape it correctly. Replace <key-file> with the path to the new key file.

Rotate a credential from an automated job

Pass the new credential from an environment variable so that it doesn’t appear in shell history or job logs. This example reads an npm auth token from NPM_AUTH_TOKEN.
To call the REST API directly, send a PATCH request to /v1/namespaces/<namespace>/package-managers with the field mask in request.update_mask.

Verify the new credential

After every update, Endor Labs checks the registry and returns the result in spec.package_manager_status. For Google Artifact Registry and AWS CodeArtifact, the check authenticates with the stored credentials. For other registries, it confirms only that the registry host is reachable, and Gradle integrations aren’t checked. To confirm that the new credential works, scan a project that resolves a dependency from the private registry. If the scan resolves the dependency, the rotation worked. If spec.package_manager_status.state is STATE_FAIL, spec.package_manager_status.error_message describes the error.

Next steps