---
title: 'StackIT Authentication'
---

Prowler authenticates with StackIT using a **service account key file**. The StackIT SDK signs the RSA challenge in the key file and mints/refreshes access tokens internally for the life of the scan, so no manual token rotation is needed.

## Service Account Key

StackIT uses RSA key-pair based service account keys. They are issued once, must be stored securely, and are read by the SDK on every scan to mint short-lived access tokens transparently.

### Option 1: Create the Key via the StackIT Portal

1. Open the [StackIT Portal](https://portal.stackit.cloud/) and select your project.
2. In the left sidebar, click **Service Accounts**.
3. Create a service account if you do not have one already. Assign:
    - `iaas.viewer` for the IaaS security group checks currently shipped, or
    - `project.owner` if you want to cover any future service Prowler adds.
4. Open the service account and go to **Service Account Keys**.
5. Click **Create key** and choose **STACKIT-generated key pair** (recommended). Download the resulting JSON file and store it securely (for example, `~/.stackit/sa-key.json`). The private material is only shown once.

### Option 2: Create the Key via the StackIT CLI

```bash
# Install the StackIT CLI from https://github.com/stackitcloud/stackit-cli first
stackit service-account key create --email my-service-account@example.com
```

## Project ID

Your StackIT project ID is a UUID. You can find it in:

1. The portal URL when viewing the project: `https://portal.stackit.cloud/projects/{PROJECT_ID}/...`
2. The project settings page
3. `stackit project list`

## Passing Credentials to Prowler

You can give Prowler either the **path** to the key file on disk or the **inline JSON content** of the key. Both go through the same StackIT SDK flow and refresh access tokens internally.

### Option A: Key File Path (workstation, persistent agents)

Recommended when the key is stored on disk.

```bash
export STACKIT_SERVICE_ACCOUNT_KEY_PATH="$HOME/.stackit/sa-key.json"
export STACKIT_PROJECT_ID="12345678-1234-1234-1234-123456789abc"

prowler stackit
```

Or as CLI flags:

```bash
prowler stackit \
  --stackit-service-account-key-path ~/.stackit/sa-key.json \
  --stackit-project-id 12345678-1234-1234-1234-123456789abc
```

<Note>
Keep the key file outside of source control and lock it down with `chmod 600 ~/.stackit/sa-key.json`. Anyone with the JSON can mint access tokens for the service account.
</Note>

### Option B: Inline Key Content (CI/CD, secret managers)

Recommended when the key is fetched at run time from a secret manager (GitHub Actions secret, AWS Secrets Manager, HashiCorp Vault, etc.) and you do not want to write it to disk.

```bash
export STACKIT_SERVICE_ACCOUNT_KEY="$(vault kv get -field=key stackit/sa)"
export STACKIT_PROJECT_ID="12345678-1234-1234-1234-123456789abc"

prowler stackit
```

<Note>
Prefer the `STACKIT_SERVICE_ACCOUNT_KEY` environment variable over the matching CLI flag (`--stackit-service-account-key`); passing the secret on the command line leaks it through process listings and shell history.
</Note>

When both the inline content and a key path are set, the inline content wins.

## Credential Lookup Order

Prowler resolves credentials in this order:

1. CLI arguments: `--stackit-service-account-key`, `--stackit-service-account-key-path`, `--stackit-project-id`
2. Environment variables: `STACKIT_SERVICE_ACCOUNT_KEY`, `STACKIT_SERVICE_ACCOUNT_KEY_PATH`, `STACKIT_PROJECT_ID`

When both the inline key and the key file path are set, the inline content takes precedence.

## Token Lifetime

Access tokens are minted on demand by the SDK from the key file and refreshed before they expire. There is nothing to rotate while Prowler is running.

## Troubleshooting

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| `401 Unauthorized` during scan | Key file is missing fields, the public key is no longer registered, or the key was revoked | Re-issue the service account key in the StackIT portal and update `STACKIT_SERVICE_ACCOUNT_KEY_PATH` |
| `403 Forbidden` during scan | Service account lacks role on the project | Re-check role assignment in the StackIT portal; `iaas.viewer` is the minimum for the shipped IaaS checks |
| `StackIT project ID must be a valid UUID` | The project ID is not in UUID format | Copy the UUID from the portal URL or `stackit project list` |
| `StackIT service account credentials are required` | None of the four credential inputs is set | Export `STACKIT_SERVICE_ACCOUNT_KEY_PATH` or `STACKIT_SERVICE_ACCOUNT_KEY` (or use their CLI counterparts) before running Prowler |