# Auth Setup

> Configure authentication for StackQL providers. Walks through credential setup for Google, AWS, Azure, GitHub, and other providers. Generates the --auth JSON string and optionally persists it.

- Skill: `stackql/auth-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stackql/auth-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stackql/auth-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: stackql (https://skillmd.com/u/stackql)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stackql/auth-setup

---


You are helping the user configure authentication for a StackQL provider.

Provider: `$0`

Follow these steps in order.

## Step 1 - Check StackQL is installed

```bash
command -v stackql
```

If not found, delegate to `/stackql-skills:install-stackql` and then continue.

## Step 2 - Check if the provider is pulled

```bash
stackql exec "SHOW PROVIDERS;" --output json
```

If the provider is not installed, delegate to `/stackql-skills:pull-provider <provider>` and then continue.

## Step 3 - Determine auth method for the provider

### Google (`google`)

Google supports two auth types:

**Option A - Service account key file (non-interactive):**
```json
{
  "google": {
    "type": "service_account",
    "credentialsfilepath": "/path/to/sa-key.json"
  }
}
```

Ask the user for the path to their service account JSON key file.

**Option B - Interactive (via gcloud):**
```json
{
  "google": {
    "type": "interactive"
  }
}
```

Requires `gcloud auth login` to have been run. Check:

```bash
command -v gcloud && gcloud auth list --filter=status:ACTIVE --format="value(account)" 2>/dev/null
```

### AWS (`awscc` or `aws`)

AWS uses environment variables or credentials file:

```json
{
  "aws": {
    "type": "aws_signing_v4",
    "credentialsenvvar": "AWS_SECRET_ACCESS_KEY",
    "keyIDenvvar": "AWS_ACCESS_KEY_ID"
  }
}
```

Check if credentials are available:

```bash
echo "${AWS_ACCESS_KEY_ID:+set}" "${AWS_SECRET_ACCESS_KEY:+set}"
test -f "$HOME/.aws/credentials" && echo "aws credentials file exists"
```

### Azure (`azure`)

Azure supports service principal or interactive auth:

**Option A - Service principal (env vars):**
```json
{
  "azure": {
    "type": "azure_default"
  }
}
```

Requires: `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`

Check:

```bash
echo "${AZURE_TENANT_ID:+set}" "${AZURE_CLIENT_ID:+set}" "${AZURE_CLIENT_SECRET:+set}"
```

**Option B - Interactive (via az cli):**

Requires `az login` to have been run. Check:

```bash
command -v az && az account show --output json 2>/dev/null
```

### GitHub (`github`)

```json
{
  "github": {
    "type": "basic",
    "credentialsenvvar": "GITHUB_TOKEN"
  }
}
```

Check:

```bash
echo "${GITHUB_TOKEN:+set}"
```

### Other providers

For providers not listed above, check the provider docs:

> I don't have specific auth instructions for `<provider>`. Check the provider documentation at `https://<provider>.stackql.io/` or use `/stackql-skills:stackql-docs <provider> authentication` to search for auth setup guidance.

## Step 4 - Build the auth JSON

Based on the user's chosen auth method and credentials, construct the `--auth` JSON string.

## Step 5 - Test the connection

Run a simple query to verify auth works:

```bash
stackql exec "SHOW SERVICES IN <provider>;" --auth='<AUTH_JSON>' --output json
```

If this fails with an auth error, help troubleshoot:
- Check credential file paths exist
- Verify env vars are set
- Suggest re-authenticating (`gcloud auth login`, `az login`, etc.)

## Step 6 - Persist (optional)

Ask the user if they want to persist the auth configuration. Options:

**Option A - Environment variable:**
Suggest adding to shell profile:
```bash
export STACKQL_AUTH='<AUTH_JSON>'
```

Then StackQL can be invoked as:
```bash
stackql exec "<SQL>" --auth="${STACKQL_AUTH}"
```

**Option B - .stackqlrc file:**
Create or update a `.stackqlrc` file:
```bash
# .stackqlrc - StackQL configuration
AUTH='<AUTH_JSON>'
```

Note: Warn the user not to commit credential files or auth JSON containing secrets to version control.

## Step 7 - Report

Confirm auth is working and suggest next steps:

> Authentication for `<provider>` is configured. You can now:
> - Explore resources: `/stackql-skills:explore <provider>`
> - Run queries: `/stackql-skills:query "SELECT ... FROM <provider>.<service>.<resource> WHERE ..."`