---
title: "Service Account Authentication"
description: "Use Nirmata Control Hub Service Account tokens to authenticate nctl for automation workflows without user credentials"
diataxis: how-to
applies_to:
  product: "nctl"
audience: ["developer","platform-engineer"]
last_updated: 2026-04-16
url: https://docs.nirmata.io/docs/nctl/service-accounts/
---


Nirmata Control Hub Service Account tokens allow `nctl` to authenticate with Nirmata Control Hub without requiring a user login. This is the recommended approach for CI/CD pipelines, GitOps workflows, and any automated scanning or publishing process where storing user credentials is not practical.

## Overview

By default, `nctl` authenticates using a user API key (set via `nctl login`, the `NIRMATA_TOKEN` environment variable, or `~/.nirmata/config`). Service Account tokens provide an alternative authentication path scoped to specific operations, making them well-suited for automation.

### Supported Operations

Service Account tokens can be used for the following `nctl` operations:

| Operation | Description |
|-----------|-------------|
| `nctl scan * --publish` | Publish scan reports to Nirmata Control Hub for any resource type (Kubernetes, Helm, Terraform, Dockerfile, JSON, repository) |
| Artifact uploads | Upload scan artifacts alongside published reports |
| Policy fetching | Read policy sets and exceptions from Nirmata Control Hub during scans |
| `nctl remediate` | Generate AI-driven remediation suggestions |

{{% alert title="Note" %}}
Cluster management operations (`nctl add cluster`, `nctl get clusters`, `nctl remove cluster`, `nctl update cluster`) and user-context operations (`nctl login`, `nctl info`, `nctl ai`) require a user API key and are not supported with Service Account tokens.
{{% /alert %}}

## Create an Nirmata Control Hub Service Account

Before using Service Account authentication, create a Service Account in Nirmata Control Hub and assign it the appropriate role.

1. Log in to [Nirmata Control Hub](https://nirmata.io)
2. Navigate to **Identity & Access** from the left sidebar
3. Go to the **Service Accounts** section and create a new Service Account
4. Assign the `reportPublisher` role (or a role with equivalent permissions) to allow scan report publishing and policy fetching
5. Copy the generated secret token — this is your `NIRMATA_SERVICE_ACCOUNT_TOKEN`

The `reportPublisher` role grants the following access:

| Permission | Description |
|------------|-------------|
| Policy set read | Fetch policy sets used during scanning |
| Policy exception read | Fetch exceptions applied during scanning |
| PRR model write | Publish scan results (`POST /policies/api/policyReportResult`) |
| Artifact upload | Upload scan artifacts (`POST /policies/api/uploadReportFiles`) |

## Configure the Token

Set the `NIRMATA_SERVICE_ACCOUNT_TOKEN` environment variable to your Service Account secret. When this variable is set, `nctl` uses it automatically for all supported operations — no `nctl login` required.

```bash
export NIRMATA_SERVICE_ACCOUNT_TOKEN="<your-service-account-secret>"
```text

{{% alert title="Note" %}}
If both `NIRMATA_SERVICE_ACCOUNT_TOKEN` and `NIRMATA_TOKEN` (or `--publish-token`) are set, the Service Account token takes precedence for scan publishing operations.
{{% /alert %}}

## Usage Examples

### CLI

```bash
export NIRMATA_SERVICE_ACCOUNT_TOKEN="<your-service-account-secret>"

# Scan and publish a Kubernetes cluster report
nctl scan kubernetes --cluster --publish

# Scan and publish a local repository
nctl scan repository /path/to/repo --publish

# Scan and publish a Helm chart
nctl scan helm /path/to/chart --publish

# Scan and publish a Terraform plan
nctl scan terraform /path/to/plan.json --publish

# Scan and publish a Dockerfile
nctl scan dockerfile /path/to/Dockerfile --publish
```text

### GitHub Actions

```yaml
name: NCTL Scan
on:
  pull_request:
    branches:
      - main

jobs:
  nctl-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      - name: Install nctl
        uses: nirmata/action-install-nctl-scan@v0.0.12

      - name: Scan and publish Kubernetes resources
        env:
          NIRMATA_SERVICE_ACCOUNT_TOKEN: ${{ secrets.NIRMATA_SERVICE_ACCOUNT_TOKEN }}
        run: nctl scan kubernetes --policies controls/pod-security --resources config-files/k8s --publish
```text

Store the Service Account token as a repository or organization secret (`NIRMATA_SERVICE_ACCOUNT_TOKEN`) in your GitHub repository settings. This avoids hardcoding credentials in your workflow files.

### GitLab CI

```yaml
nctl-scan:
  image: ubuntu:latest
  variables:
    NIRMATA_SERVICE_ACCOUNT_TOKEN: $NIRMATA_SERVICE_ACCOUNT_TOKEN
  script:
    - curl -LO https://downloads.nirmata.io/nctl/stablereleases/nctl_linux_amd64.zip
    - unzip nctl_linux_amd64.zip && chmod u+x nctl && mv nctl /usr/local/bin/
    - nctl scan repository . --publish
```text

## Token Expiry

Service Account tokens may have an expiry depending on your Nirmata Control Hub account configuration. When a token expires:

- For CLI usage, update the `NIRMATA_SERVICE_ACCOUNT_TOKEN` environment variable with a new token
- For CI/CD pipelines, update the secret in your pipeline configuration

To check or manage token expiry settings, navigate to **Identity & Access** → **API Tokens** in Nirmata Control Hub.