# Chainguard Libraries access

URL: https://chainguard-docs-preview-git-uv-frozen-installs.chainguard.app/chainguard/libraries/introduction/access.md
Last Modified: October 16, 2026
Tags: Chainguard Libraries

Learn how to access Chainguard Libraries for enhanced security in Java and Python dependencies, including authentication and organization setup


Chainguard Libraries provide controlled access to security-enhanced Java and
Python dependencies through the unified Chainguard platform authentication
system. This guide explains how to access (download) Chainguard library artifacts for your organization.

## Getting started

### Prerequisites

- Ensure you have access to Chainguard Libraries.
    - If you are not a Chainguard user yet, create a Chainguard account. To add
an entitlement to Chainguard Libraries for your organization, contact your
Chainguard account team.
- If you have access to more than one Chainguard organization, confirm the name
of the one you want to use. You can then pass it to `chainctl` commands with the
`--parent` parameter.

### Direct access vs. artifact manager

There are two approaches to access: Using an artifact manager or
direct access.

#### Artifact manager

If your organization uses an artifact manager such as Cloudsmith, JFrog Artifactory, or Sonatype Nexus, you can set up and configure credentials once per language ecosystem. Then, all projects and developers automatically inherit
the configuration. This option is recommended for organizations with multiple
teams, and provides centralized access controls and consistent uptime.

#### Direct access

Set up authentication directly in each project's build
configuration. This option allows for faster initial setup, but it does not
allow for global configuration. It requires configuration per project and
workstation, which creates more overhead as you scale across teams and projects.

Both approaches require pull tokens for authentication; refer to [Pull token
characteristics and use](#pull-token-characteristics-and-use) for more information.

A check in [Chainguard Checks](/chainguard/checks/overview/) doesn't need a pull token. It can download JavaScript and Python libraries through a [workload identity](/chainguard/checks/identity-and-trust/#chainguard-hosts) that holds the `libraries.javascript.pull` or `libraries.python.pull` role. A [Chainguard Workspaces](/chainguard/workspaces/overview/) session has no credential for Chainguard Libraries, as described in [Credentials a session can't supply](/chainguard/workspaces/credentials/#credentials-a-session-cant-supply).

> **Note**: For Python users, the [Chainguard keyring
> provider](/chainguard/libraries/introduction/access/#python-keyring-provider)
> uses short-lived credentials and is the preferred method where your
> environment supports it.


### Initial authentication

Once your user account is created and access is confirmed, [install the
Chainguard Control `chainctl` command line
tool](/platform/chainctl-usage/how-to-install-chainctl/) and log in to your
account:

```shell
chainctl auth login
```

<blockquote>
<p><strong>Note</strong>: <code>chainctl auth login</code> supports several login flows, including device-code login for machines without a browser and assumable identities for CI. If the default browser flow doesn't work in your environment, see <a href="/platform/chainctl-usage/authentication-options/">Authentication options</a>.</p>
</blockquote>


After authentication in a browser window, a successful login displays a message
and a token:

```output
Successfully exchanged token.
Valid! Id: 8a4141a........7d9904d98c
```

<a id="pull-token"></a>

## Creating pull tokens for libraries

Pull tokens authenticate requests to download library artifacts from Chainguard. You can create the pull tokens:

- With [the chainctl command](#creating-pull-tokens-with-chainctl), or
- [Using the Chainguard
  console](#creating-pull-tokens-with-the-chainguard-console).

For environments where short-lived credentials are not suitable, such as some
CI/CD platforms, you can generate a pull token, which provides longer-lived
access to Chainguard Libraries.

To create a pull token you must have the relevant [entitlement](#entitlement)
for the ecosystem and the `libraries.java.pull_token_creator`,
`libraries.javascript.pull_token_creator`, or
`libraries.python.pull_token_creator` role.

### Creating pull tokens with chainctl

Create a new pull token for the Chainguard Libraries for Java with the [chainctl
auth pull-token](/platform/chainctl/chainctl-docs/chainctl_auth_pull-token/)
command:

```shell
chainctl auth pull-token --repository=java --ttl=8670h
```

- `--repository=java`: retrieve the token for use with [Chainguard Libraries for
  Java](/chainguard/libraries/java/overview/). Use `python` for a token to use
  [Chainguard Libraries for Python](/chainguard/libraries/python/overview/) and
  `javascript` for a token to use [Chainguard Libraries for
  JavaScript](/chainguard/libraries/javascript/overview/).
- `--ttl=8670h`: set the duration for the validity of the token, defaults to
  `720h` (equivalent to 30 days), maximum valid value is `8760h` (equivalent to
  365 days), valid unit strings range from nanoseconds to hours and are `ns`,
  `us`, `ms`, `s`, `m`, and `h`.

Use the optional `--name` flag to supply a meaningful and short name for the
token, to be able to locate it easier at a later stage.

If you belong to a single organization, `chainctl` selects it automatically. If
you have access to more than one, it asks “With which location is the pull token
associated?” Use the arrow keys to select the organization that has the
entitlement to access Chainguard Libraries for Java, and press `/` to filter the
list. Pass `--parent=<organization>` to skip the prompt.

`chainctl` returns a username and password suitable for basic authentication in
the response:

```output
Username: <identity-id>

Password: <pull-token>
```

### Creating pull tokens with the Chainguard Console

Follow these steps to create a pull token for Chainguard Libraries in the
Chainguard console:

1. Use your authentication details to access the console at
  [https://console.chainguard.dev/](https://console.chainguard.dev/).
2. In the left-hand navigation, click **Overview**.
3. Click the **Manage pull tokens** link, then click **Create token**.
    - Alternatively, select **Access Tokens** from the menu on the
      **Settings** page.
4. Configure the access token:
    - **Name**: Provide a name. The name can later be used to locate the token
  in the list.
    - **Description**: Optionally provide a description of the token.
    - **Access**: Choose the library that this token should access.
    - **Expiration**: Set an expiration date for the token. The default is 30
      days.
5. Click **Create token**.
6. When the username and password values are displayed, save them in a secure
   location. You need them to use the pull token, and the console doesn't
   display them again.

## Pull token characteristics and use

The username is the identity ID of the pull token identity that `chainctl` just
created, and the password is the token itself. `chainctl` labels the same two
values `identity_id` and `token` with `--output=json`, and
`CHAINGUARD_JAVA_IDENTITY_ID` and `CHAINGUARD_JAVA_TOKEN` with `--output=env`.
Refer to [pull token output formats and credential
names](/platform/chainctl-usage/pull-token-output/) for the full mapping.

The returned username and password combination is a new credential set in the
organization that is independent of the account used to create and retrieve the
credential set. It is therefore suitable for use in any service application,
such as a repository manager or a build tool that is not tied to a specific
user. You can also use the token as an individual for your development with
direct access to Chainguard Libraries.

To use the pull token in another environment, supply the username and password
for basic authentication. Note that the actual returned values are much longer.

> **Note**: Chainguard does not offer an SLA for uptime availability of the
> Chainguard Libraries repositories at `libraries.cgr.dev`. To reduce production
> risk and ensure reliability, we recommend proxying the repositories through
> your own artifact repository whenever possible.


For artifact manager setup, see the global configuration guides:

- [Java](/chainguard/libraries/java/global-configuration/)
- [JavaScript](/chainguard/libraries/javascript/global-configuration/)
- [Python](/chainguard/libraries/python/global-configuration/)

For direct access, see the build configuration guides:

- [Java](/chainguard/libraries/java/build-configuration/)
- [JavaScript](/chainguard/libraries/javascript/build-configuration/)
- [Python](/chainguard/libraries/python/build-configuration/)

<a name="env"></a>

### Use environment variables for pull token credentials

Using environment variables for username and password is more secure than hard
coding the values in configuration files. In addition, you can use the same
configuration and files for all users to simplify setup and reduce errors.

Use the `env` environment output option to create a snippet for a new token
suitable for integration in a script.

```shell
$ chainctl auth pull-token --output env --repository=java
export CHAINGUARD_JAVA_IDENTITY_ID=<identity-id>
export CHAINGUARD_JAVA_TOKEN=<pull-token>
```

Combine the call with `eval` to populate the environment variables directly by
calling `chainctl`:

```shell
eval $(chainctl auth pull-token --output env --repository=java)
```

Equivalent commands for Python and JavaScript are supported and result in values
for the `CHAINGUARD_PYTHON_IDENTITY_ID`/`CHAINGUARD_PYTHON_TOKEN` and
`CHAINGUARD_JAVASCRIPT_IDENTITY_ID`/`CHAINGUARD_JAVASCRIPT_TOKEN` variables.

Use the export commands in a `~/.env` or similar file or use your preferred
secrets management application to reuse the token in multiple sessions. Source
the file or load the secrets from the app to have access to the tokens in your
shell session, including build configurations file that can load from
environment variables, for example a Maven `settings.xml` file.

Running this command as part of a login script or some other automation allows
your organization to replace actual username and password values in your build
tool configuration with environment variable placeholders:

- [Java build tool
  configuration](/chainguard/libraries/java/build-configuration/)
- [JavaScript build tool
  configuration](/chainguard/libraries/javascript/build-configuration/)
- [Python build tool
  configuration](/chainguard/libraries/python/build-configuration/)

#### uv index-scoped environment variables

When using `uv` for Python, you can supply credentials through index-scoped
environment variables instead of a shared secrets file or `.netrc`. For a named
index, uv reads `UV_INDEX_<NAME>_USERNAME` and `UV_INDEX_<NAME>_PASSWORD`, where
`<NAME>` is the index name uppercased with hyphens replaced by underscores.

For an index named `chainguard`, set:

```shell
export UV_INDEX_CHAINGUARD_USERNAME="${CHAINGUARD_PYTHON_IDENTITY_ID}"
export UV_INDEX_CHAINGUARD_PASSWORD="${CHAINGUARD_PYTHON_TOKEN}"
```

This pairs well with the `eval` approach above: generate the
`CHAINGUARD_PYTHON_IDENTITY_ID` and `CHAINGUARD_PYTHON_TOKEN` variables, then
map them to uv's index-scoped names. Refer to the [uv build
configuration](/chainguard/libraries/python/build-configuration/#uv) for index
setup details.

<a id="netrc"></a>

### .netrc for authentication

[curl](https://curl.se/) and a number of other tools support configuration of
username and password authentication details for a specific domain in the
[`.netrc`
file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html),
typically located in the user's home directory.

Use this approach for authentication to a repository manager in your
organization or to Chainguard Libraries directly, for example with [pip and
others for Chainguard Libraries for
Python](/chainguard/libraries/python/build-configuration/#pip), with [bazel for
Chainguard Libraries for
Java](/chainguard/libraries/java/build-configuration/#bazel) or for manual
testing with curl.

The following example shows a suitable setup for a repo manager available at
`repo.example.com`:

```bash
machine repo.example.com
login YOUR_USERNAME_FOR_REPOSITORY_MANAGER
password YOUR_PASSWORD
```

For a direct connection to Chainguard Libraries, for example for testing with
curl, use the following example with the username
`CHAINGUARD_PYTHON_IDENTITY_ID` and password `CHAINGUARD_PYTHON_TOKEN` value for
the pull token for the desired language ecosystem:

```bash
machine libraries.cgr.dev
login CHAINGUARD_PYTHON_IDENTITY_ID
password CHAINGUARD_PYTHON_TOKEN
```

Note that the long string for the password value must use only one line.

When you use this `.netrc` file in a container build, mount it as a build secret rather than copying it into an image layer. See [Container builds](/chainguard/libraries/policies-and-security/build-containers/).

### Verification

Use the credentials for manual testing in a browser or with a script and curl if
you know the URL for a specific library artifact. Refer to the following
sections for more details:

- [Technical details and manual testing for Java
  libraries](/chainguard/libraries/java/overview/#technical-details)
- [Technical details and manual testing for JavaScript
  libraries](/chainguard/libraries/javascript/overview/#technical-details)
- [Technical details and manual testing for Python
  libraries](/chainguard/libraries/python/overview/#technical-details)
- [Use environment variables](#env)
- [.netrc for authentication](#netrc)

<a id="python-keyring"></a>

## Python keyring provider

Python users can leverage an alternative to pull tokens. The [Chainguard keyring
implementation](https://github.com/chainguard-dev/keyrings-chainguard-libraries)
provides short-lived credentials from supported environments, such as local
development and CI/CD platforms that can use [assumable
identities](/platform/administration/assumable-ids/assumable-ids/).

Where possible, Chainguard recommends using short-lived credentials to access
Chainguard Libraries.

To set up the keyring, install the `keyrings-chainguard-libraries` package:

```shell
pip install keyrings-chainguard-libraries
```

*Note:* If you haven't set up access to Chainguard Libraries for Python, the
above command installs the package from PyPI. After installing and configuring
Chainguard Libraries for Python, you can get the private package again, to get
the package built by Chainguard. To re-install the package:

```bash
pip install keyrings-chainguard-libraries --ignore-installed --no-cache-dir
```

Once the keyring package is installed, when you request to install packages from
Chainguard Libraries for Python, the keyring automatically retrieves short-lived
credentials for you, using `chainctl`.

To use the keyring with a project `uv`, install the keyring:

```shell
uv pip install keyrings-chainguard-libraries
```

*Note:* If you haven't set up access to Chainguard Libraries for Python, the
above command installs the package from PyPI. After installing and configuring
Chainguard Libraries for Python, you can get the private package again, to get
the package built by Chainguard. To re-install the package:

```shell
uv pip install keyrings-chainguard-libraries --reinstall --no-cache
```

By default, [uv disables keyring
auth](https://docs.astral.sh/uv/reference/settings/#keyring-provider).

To enable it in the global uv.toml:

```toml
keyring-provider = "subprocess"
```

To enable it in a project-specific pyproject.toml:

```toml
[tool.uv]
keyring-provider = "subprocess"
```

<a id="pull-token-management"></a>

## Pull token management

Pull tokens are separate identities with username and password that are used for
access to Chainguard Libraries. The tokens have a limited Time to Live (TTL)
with a default of 30 days and a maximum TTL of 365 days.

As a result, pull tokens become invalid after the TTL and are flagged as
expired. For your use of Chainguard Libraries you must replace the token with a
new one.

Expired tokens can no longer be used for access to Chainguard Libraries, but
otherwise do not cause any issues and continue to exist until you delete them.

Inspect all pull tokens for your organization in the Chainguard console:

- Use your authentication details to access the console at
  [https://console.chainguard.dev/](https://console.chainguard.dev/).
- Select **Overview** in the left-hand navigation.
- Select the **Manage pull tokens** link.
    - Alternatively, select **Settings** in the left-hand navigation, and select
    **Access Tokens** in the menu on the settings page.

The list includes the following columns:

- **Name** - the name of the pull token. Expired pull tokens show an
  **Expired** warning.
- **Description** - the description of the pull token.
- **Access** - what the pull token can pull, such as **Java Libraries**.
- **Created** - the date when the pull token was created.
- **Expiration** - string description of the expiration status of the token,
  such as *in 8 months* or *4 days ago*.
- **Actions** - menu button to perform actions on the pull token: **Delete**
  and **Edit**.

Use the action to remove a pull token:

- Locate the row of the desired pull token, typically an expired token.
- Use the menu button in the **Actions** column of the same row and select
  **Delete**.
- Confirm the deletion in the dialog by pressing **Delete pull token**.

Alternatively use chainctl with the [auth
pull-token](/platform/chainctl/chainctl-docs/chainctl_auth_pull-token/) and
[iam identities](/platform/chainctl/chainctl-docs/chainctl_iam_identities/)
commands for various inspection and management tasks.

List all pull tokens with the `list` command:

```shell
chainctl auth pull-token list
```

The displayed list includes the following columns:

- **ID** - the identifying username of the pull token
- **NAME** - the name of the pull token
- **DESCRIPTION** - the description of the pull token
- **ROLES** - the assigned organization and role for the pull token. The value
  shows the name of the organization separate from the role with a colon. Valid
  roles are all pull authorization from for apk packages `apk.pull`, container
  images `registry.pull`, Python libraries `libraries.python.pull`, Java
  libraries `libraries.java.pull`, and JavaScript libraries
  `libraries.javascript.pull` .
- **EXPIRES** - the number of days until the end of the TTL period. Negative
  values indicate expired tokens.

List all pull tokens for Chainguard Libraries for Java that are not yet expired:

```shell
chainctl auth pull-token list --repository=java
```

List all expired pull tokens for Chainguard Libraries for Python:

```shell
chainctl auth pull-token list --repository=python --expired=true
```

Use the [delete command for IAM
identities](/platform/chainctl/chainctl-docs/chainctl_iam_identities_delete/)
to delete a specific pull token using its ID `45a0c61ea6fd97...`:

```shell
chainctl iam identities delete 45a0c61ea6fd97...
```

Use the identifier or name of your organization `example` and the `--expired`
flag to remove all expired pull tokens:

```shell
chainctl iam ids rm --expired
```

<a id="entitlement"></a>

## Manage library entitlements

An entitlement grants your organization access to a Chainguard Libraries
ecosystem. To add or remove an entitlement, contact your Chainguard account
team.

Once your organization is entitled to an ecosystem, you can enable upstream
fallback and list your entitlements yourself with [`chainctl libraries
entitlements`](/platform/chainctl/chainctl-docs/chainctl_libraries_entitlements/).

### Enable upstream fallback

To enable upstream fallback for an entitled ecosystem, use the `--policy` flag:

```bash
chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM
```

To update the upstream fallback policy on an existing entitlement, rerun the
command with the new `--policy` value.

### List entitlements

You can verify entitlements for your organization `example.com` to verify which ecosystems are enabled:

```shell
chainctl libraries entitlements list
```

The output includes the ecosystem and configured policy in the table:

```output
Ecosystem Library Entitlements for example (45a0...p7q)

                            ID                             | ECOSYSTEM  |             POLICY
-----------------------------------------------------------|------------|--------------------------------
 45a0c61a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q/12345abc67890 | JAVASCRIPT | POLICY_CHAINGUARD_AND_UPSTREAM
 45a0c61a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q/45678abc67890 | JAVA       | POLICY_CHAINGUARD
 45a0c61a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q/56789abc67890 | PYTHON     | POLICY_CHAINGUARD
```

<a id="policy"></a>

## Manage library policies

Users with the Owner role can create, enable, disable, and list library policies using [`chainctl libraries policy`](/platform/chainctl/chainctl-docs/chainctl_libraries_policy/) commands. These policies apply to all packages pulled through Chainguard Repository. The [upstream fallback](/chainguard/libraries/introduction/overview/#upstream-fallback-and-controls) must be enabled for an ecosystem in order to use policies.

Learn about how to manage policies in the [Libraries policies page](/chainguard/chainguard-repository/library-policies/).