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

# How to authenticate in Container Registry

You can authenticate in Container Registry with the help of a short-lived [access token](/iam/authorization/access-tokens) issued by the Nebius AI Cloud CLI each time, or with a long-lived [static key token](/iam/authorization/static-keys) issued for the Container Registry service.

* For a [local machine](#working-on-a-local-machine), use a Docker credentials helper.
* For a [CI/CD environment](#working-in-a-ci/cd-environment), use a service account and either issue a [long-lived static key](#long-lived-static-key-token) and save it in your pipeline settings, or get a [short-lived token](#short-lived-access-token) each time your pipeline runs.

## Working on a local machine

On your local machine, you can simply configure a Docker credentials helper to work with Container Registry.

1. Run the following command:

   ```bash theme={null}
   nebius registry configure-helper
   ```

2. Check that the credentials helper is configured:

   1. Open the the file from the previous command output, for example, with the `cat` command:

      ```bash theme={null}
      cat /Users/user/.docker/config.json
      ```

   2. Check that the `credHelpers` property contains the following lines:

      ```json theme={null}
      "cr.eu-north1.nebius.cloud": "nebius"
      "cr.eu-north2.nebius.cloud": "nebius"
      "cr.eu-west1.nebius.cloud": "nebius"
      "cr.me-west1.nebius.cloud": "nebius"
      "cr.uk-south1.nebius.cloud": "nebius"
      "cr.us-central1.nebius.cloud": "nebius"
      ```

When you run any `docker` command after this configuration, it requests credentials from `nebius`, which might require you to log in with the help of the [web console](https://console.nebius.com).

## Working in a CI/CD environment

In your CI/CD environment, you are unlikely to be able to log into the web console. Therefore, you need to [create a service account](/iam/service-accounts/manage#create-a-service-account) and use it to get credentials. Make sure that the service account is in a [group](/iam/authorization/groups) that has at least the `viewer` role within your tenant; for example, the default `viewers` group.

There are two ways to work with a service account:

* Issue a long-lived [static key](/iam/authorization/static-keys) for Container Registry.
* Get a short-lived [access token](/iam/authorization/access-tokens) in each run of your pipeline job.

### Long-lived static key token

To use a long-lived token, you need to [issue a static key](/iam/authorization/static-keys/manage) and store the token in your CI/CD environment configuration.

1. Create a static key for your service account:

   ```bash theme={null}
   nebius iam static-key issue \
     --account-service-account-id=<service_account_ID> \
     --service=CONTAINER_REGISTRY
   ```

   By default, the key lifetime is 6 months. If you need a different lifetime, add the `--expires-at` parameter to this command. It accepts the date of expiration in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, for example `2025-11-23T11:44:43.232142Z`. You can set a lifetime of up to 3 years.

2. Get the static key token from the `token` parameter of the output.

3. Configure the job that works with Container Registry to use this token:

   ```bash theme={null}
   docker login cr.<region>.nebius.cloud \
     --username iam \
     --password <token>
   ```

   In this command, set the [region](/overview/regions) of the registry with which the pipeline is working.

### Short-lived access token

To use a short-lived access token, you need to get it from Nebius AI Cloud CLI, which should be installed in your CI/CD environment. Access tokens have a lifetime of 12 hours.

1. Create an [authorized key](/iam/service-accounts/authorized-keys) for your service account.
2. [Install the Nebius AI Cloud CLI](/cli/install) in your environment.
3. [Configure a profile](/iam/service-accounts/authorized-keys#configure-your-profile) for your service account in the `.nebius/config.yaml` file.
4. Configure the job that works with Container Registry to generate credentials with <code>nebius</code> and pipe them directly into a `docker` command:

   ```bash theme={null}
   nebius iam get-access-token | \
     docker login cr.<region>.nebius.cloud \
       --username iam \
       --password-stdin
   ```

   In this command, set the [region](/overview/regions) of the registry with which the pipeline is working.

You can do the same if you are using `helm registry login`:

```bash theme={null}
nebius iam get-access-token | \
  helm registry login cr.<region>.nebius.cloud \
    --username iam \
    --password-stdin
```

## Troubleshooting

If you are getting the "Permission denied" error when trying to access Container Registry from your [local machine](#working-on-a-local-machine), double-check that the Docker credentials helper was configured correctly:

* Check that the system can find the Nebius AI Cloud CLI binary:

  ```bash theme={null}
  which nebius
  ```

  It should return a path, for example:

  ```bash theme={null}
  /home/user/.nebius/bin/nebius
  ```

  If it does not, reinstall Nebius AI Cloud CLI, and then rerun <code>nebius registry configure-helper</code>.

* Check that the system can find the credentials helper:

  ```bash theme={null}
  which docker-credential-nebius
  ```

  It should return a path, for example:

  ```bash theme={null}
  /home/user/.nebius/bin/docker-credential-nebius
  ```

  If it does not, rerun <code>nebius registry configure-helper</code>.

* Check that the region of the registry you are trying to access is present in the `.docker/config.json` file:

  ```json theme={null}
  "cr.<region>.nebius.cloud": "nebius"
  ```

  If it is not, add it manually or rerun <code>nebius registry configure-helper</code>.