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

# Docker authentication

> Authenticate Docker and OCI clients with the registry

The Artifact Store implements the Docker Registry API v2 and accepts standard Docker authentication. You can authenticate using the Mistrive CLI for interactive sessions or service account keys for automation.

## Image path format

Images in the Artifact Store follow this path structure:

```
registry.example.com/{project_id}/{repository_id}/{image}:{tag}
```

For example:

```
registry.example.com/my-project/backend/api-server:v1.2.3
```

* **registry.example.com** — Your Artifact Store hostname
* **my-project** — Project ID (not display name)
* **backend** — Repository ID
* **api-server** — Image name
* **v1.2.3** — Tag

## Authentication methods

<Tabs>
  <Tab title="Mistrive CLI">
    The Mistrive CLI generates short-lived Docker credentials from your browser session.

    ```bash theme={null}
    mistrive --endpoint api.example.com auth docker | docker login registry.example.com -u cli --password-stdin
    ```

    This command:

    1. Opens your browser to authenticate (if not already logged in)
    2. Generates a Docker credential token
    3. Pipes it to `docker login`

    ### Installing the CLI

    <Tabs>
      <Tab title="macOS (Apple Silicon)">
        ```bash theme={null}
        curl -L https://cli.mistrive.com/mistrive-darwin-arm64 -o mistrive
        chmod +x mistrive
        sudo mv mistrive /usr/local/bin/
        ```

        SHA256: `2f1d78ff49478c6fc9c95c20b0d4a547d3acde3ba1c41912254cc6a8bd66f137`
      </Tab>

      <Tab title="Linux (AMD64)">
        ```bash theme={null}
        curl -L https://cli.mistrive.com/mistrive-linux-amd64 -o mistrive
        chmod +x mistrive
        sudo mv mistrive /usr/local/bin/
        ```

        SHA256: `6fc7dded16bb48d5a478aee9cc6da942e2cb988a41e1c4746c69ac5187c9161a`
      </Tab>
    </Tabs>

    Use this method for local development and interactive workflows where you're working at a terminal.
  </Tab>

  <Tab title="Service account key">
    For CI/CD pipelines and automation, use a service account key.

    First, [create a service account](/user-guides/service-accounts) and download its JSON key file. Then authenticate using base64 encoding:

    ```bash theme={null}
    cat key.json | base64 -b 0 | docker login registry.example.com -u _json_b64 --password-stdin
    ```

    <Info>
      The username `_json_b64` tells the registry to expect a base64-encoded JSON key as the password.
    </Info>

    On Linux, use `base64 -w 0` instead of `base64 -b 0`:

    ```bash theme={null}
    cat key.json | base64 -w 0 | docker login registry.example.com -u _json_b64 --password-stdin
    ```

    For GitHub Actions, store the base64-encoded key as a secret:

    ```yaml theme={null}
    - name: Login to Artifact Store
      run: |
        echo "${{ secrets.MISTRIVE_KEY }}" | docker login registry.example.com -u _json_b64 --password-stdin
    ```
  </Tab>
</Tabs>

## Pushing images

After authenticating, push images using standard Docker commands.

Tag your image with the full registry path:

```bash theme={null}
docker tag my-image:latest registry.example.com/my-project/backend/my-image:latest
```

Push to the registry:

```bash theme={null}
docker push registry.example.com/my-project/backend/my-image:latest
```

<Note>
  You need **Editor** access to the repository (or inherited from project/organization) to push images.
</Note>

## Pulling images

Pull images using the full registry path:

```bash theme={null}
docker pull registry.example.com/my-project/backend/my-image:latest
```

You need **Viewer** access to pull images. For public repositories (where `allUsers` has Viewer access), no authentication is required.

## CI/CD integration examples

### GitHub Actions

```yaml theme={null}
name: Build and Push

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Login to Artifact Store
        run: |
          echo "${{ secrets.MISTRIVE_KEY }}" | docker login registry.example.com -u _json_b64 --password-stdin
      
      - name: Build and push
        run: |
          docker build -t registry.example.com/my-project/app/web:${{ github.sha }} .
          docker push registry.example.com/my-project/app/web:${{ github.sha }}
```

### GitLab CI

```yaml theme={null}
build:
  image: docker:latest
  services:
    - docker:dind
  script:
    - echo "$MISTRIVE_KEY" | docker login registry.example.com -u _json_b64 --password-stdin
    - docker build -t registry.example.com/my-project/app/web:$CI_COMMIT_SHA .
    - docker push registry.example.com/my-project/app/web:$CI_COMMIT_SHA
```

Store `MISTRIVE_KEY` as a CI/CD variable containing the base64-encoded service account key.

## Troubleshooting

### "unauthorized: authentication required"

This error indicates either missing credentials or insufficient permissions.

* Verify you've run `docker login` successfully
* Check that your user or service account has at least **Viewer** access for pulls, **Editor** for pushes
* Confirm the project and repository IDs in the image path are correct

### "denied: access forbidden"

Your credentials are valid but lack permission for the requested operation.

* For pushing: ensure **Editor** or **Owner** access on the repository
* For pulling: ensure **Viewer** or higher access on the repository
* Check [permission inheritance](/user-guides/permissions) to understand where access might be blocked

### "name unknown: repository not found"

The specified repository doesn't exist or you don't have permission to see it.

* Verify the project ID and repository ID
* Ensure you have at least **Viewer** access to the project to see its repositories