> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endorlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate private package manager credentials

> Replace the password, token, or key that Endor Labs uses to reach a private registry with endorctl or the REST API.

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](https://docs.endorlabs.com/developers-api/cli/install-and-configure.md) 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](https://docs.endorlabs.com/platform-administration/rbac/authorization-roles.md) 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.


&#x20; \- Ecosystem: Maven
&#x20; Credential: Username and password
&#x20; Field mask: \`spec.mvn.basic\_auth.password\`
&#x20; \- Ecosystem: Maven
&#x20; Credential: Token
&#x20; Field mask: \`spec.mvn.token\_auth.token\`
&#x20; \- Ecosystem: Maven
&#x20; Credential: Password (legacy field)
&#x20; Field mask: \`spec.mvn.password\`
&#x20; \- Ecosystem: PyPI
&#x20; Credential: Username and password
&#x20; Field mask: \`spec.pypi.basic\_auth.password\`
&#x20; \- Ecosystem: PyPI
&#x20; Credential: Token
&#x20; Field mask: \`spec.pypi.token\_auth.token\`
&#x20; \- Ecosystem: PyPI
&#x20; Credential: Password (legacy field)
&#x20; Field mask: \`spec.pypi.password\`
&#x20; \- Ecosystem: RubyGems
&#x20; Credential: Username and password
&#x20; Field mask: \`spec.gem.basic\_auth.password\`
&#x20; \- Ecosystem: RubyGems
&#x20; Credential: Token
&#x20; Field mask: \`spec.gem.token\_auth.token\`
&#x20; \- Ecosystem: RubyGems
&#x20; Credential: Password (legacy field)
&#x20; Field mask: \`spec.gem.password\`
&#x20; \- Ecosystem: NuGet
&#x20; Credential: Username and password
&#x20; Field mask: \`spec.nuget.basic\_auth.password\`
&#x20; \- Ecosystem: NuGet
&#x20; Credential: Token
&#x20; Field mask: \`spec.nuget.token\_auth.token\`
&#x20; \- Ecosystem: NuGet
&#x20; Credential: Password (legacy field)
&#x20; Field mask: \`spec.nuget.password\`
&#x20; \- Ecosystem: npm
&#x20; Credential: Base64-encoded \`username:password\`
&#x20; Field mask: \`spec.npm.token\`
&#x20; \- Ecosystem: npm
&#x20; Credential: Auth token
&#x20; Field mask: \`spec.npm.auth\_token\`
&#x20; \- Ecosystem: Gradle
&#x20; Credential: Property value
&#x20; Field mask: \`spec.gradle.property\_key\_value\`
&#x20; \- Ecosystem: Packagist
&#x20; Credential: Password or token
&#x20; Field mask: \`spec.packagist.password\`
&#x20; \- Ecosystem: Swift
&#x20; Credential: Username and password
&#x20; Field mask: \`spec.swift.basic\_auth.password\`
&#x20; \- Ecosystem: Swift
&#x20; Credential: Access token
&#x20; Field mask: \`spec.swift.token\`
&#x20; \- Ecosystem: Conan
&#x20; Credential: Username and password
&#x20; Field mask: \`spec.conan.basic\_auth.password\`
&#x20; \- Ecosystem: Google Artifact Registry
&#x20; Credential: Service account key
&#x20; Field mask: \`spec.auth\_provider.gar.service\_account\_key\`
&#x20;&#x20;

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](https://docs.endorlabs.com/integrations/package-managers/mtls-authentication.md) 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.

   ```bash theme={null}
   endorctl api list -r PackageManager -n <namespace> --field-mask uuid,meta.name,spec
   ```

   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`.

   > [!NOTE]
   >
   > 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](#credential-fields-by-ecosystem).

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`.

   ```bash theme={null}
   endorctl api update -r PackageManager \
     -n <namespace> \
     --uuid <package-manager-uuid> \
     --field-mask spec.mvn.basic_auth.password \
     -d '{"spec": {"mvn": {"basic_auth": {"password": "<new-password>"}}}}'
   ```

   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.

> [!WARNING]
>
> 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.

```bash theme={null}
endorctl api update -r PackageManager \
  -n <namespace> \
  --uuid <package-manager-uuid> \
  --field-mask spec.auth_provider.gar.service_account_key \
  -d "$(jq -n --rawfile key <key-file> '{spec: {auth_provider: {gar: {service_account_key: $key}}}}')"
```

## 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`.

```bash theme={null}
endorctl api update -r PackageManager \
  -n "$ENDOR_NAMESPACE" \
  --uuid "$PACKAGE_MANAGER_UUID" \
  --field-mask spec.npm.auth_token \
  -d "$(jq -n --arg token "$NPM_AUTH_TOKEN" '{spec: {npm: {auth_token: $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`.

```bash theme={null}
curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/package-managers" \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --request PATCH \
  --data "$(jq -n --arg uuid "$PACKAGE_MANAGER_UUID" --arg token "$NPM_AUTH_TOKEN" \
    '{request: {update_mask: "spec.npm.auth_token"}, object: {uuid: $uuid, spec: {npm: {auth_token: $token}}}}')"
```

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

* See [Private package manager integrations](https://docs.endorlabs.com/integrations/package-managers.md) to set up an integration for another ecosystem.
* See [endorctl api](https://docs.endorlabs.com/developers-api/cli/commands/api.md) to learn more about the update command and its flags.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.