| name | sigma-api |
| description | Authenticate against the Sigma Computing REST API and obtain a bearer token. Use whenever the user wants to call the Sigma API directly with curl/HTTP, exchange OAuth client credentials for an access token, configure SIGMA_BASE_URL / SIGMA_CLIENT_ID / SIGMA_CLIENT_SECRET, troubleshoot 401/403 responses, or pick the right Sigma API hostname for their cloud. Use as a prerequisite when another Sigma skill needs an SIGMA_API_TOKEN. |
Sigma REST API Authentication
Authenticate against the Sigma Computing REST API and obtain a bearer token. This skill is a prerequisite for any skill that calls the Sigma API directly with curl.
curl, jq, and base64 must be available. curl and base64 ship with macOS and most Linux distros; jq usually does not — install with brew install jq (macOS) or apt install jq (Debian/Ubuntu).
Base URL Selection
The host depends on the user's Sigma cloud and region. Confirm with the user before exporting. The user can also look up their base URL in Administration → Developer Access in the Sigma app.
The authoritative list lives in the Sigma help docs: Supported regions, data platforms, and features. Mirror below:
| Cloud | Region | Base URL |
|---|
| AWS | US West (Oregon) | https://aws-api.sigmacomputing.com |
| AWS | US East (N. Virginia) | https://api.us-a.aws.sigmacomputing.com |
| AWS | Canada (Central) | https://api.ca.aws.sigmacomputing.com |
| AWS | Europe (Frankfurt) | https://api.eu.aws.sigmacomputing.com |
| AWS | Asia Pacific (Sydney) | https://api.au.aws.sigmacomputing.com |
| AWS | UK (London) | https://api.uk.aws.sigmacomputing.com |
| Azure | US (Virginia) | https://api.us.azure.sigmacomputing.com |
| Azure | Europe (Netherlands) | https://api.eu.azure.sigmacomputing.com |
| Azure | Canada (Toronto) | https://api.ca.azure.sigmacomputing.com |
| Azure | UK (London) | https://api.uk.azure.sigmacomputing.com |
| GCP | US (Iowa) | https://api.sigmacomputing.com |
| GCP | Saudi Arabia (Dammam) | https://api.sa.gcp.sigmacomputing.com |
SIGMA_BASE_URL is the API host, not the app URL — https://aws-api.sigmacomputing.com, not https://app.sigmacomputing.com.
Step 1 — Set Credentials
Where to find credentials: Sigma admin settings → Administration → APIs and Tokens (also surfaced as Developer Access → API credentials).
export SIGMA_BASE_URL="https://aws-api.sigmacomputing.com"
export SIGMA_CLIENT_ID="your-client-id"
export SIGMA_CLIENT_SECRET="your-client-secret"
Step 2 — Exchange Credentials for a Bearer Token
Sigma uses the OAuth 2.0 client credentials grant with HTTP Basic auth on the token endpoint. Tokens are short-lived (~1 hour TTL).
Preferred: bundled helper script
scripts/get-token.sh reads the three env vars, fails loudly on missing inputs or non-2xx responses, and prints a single export SIGMA_API_TOKEN=... line. eval it to load the token into the current shell:
- Claude Code:
eval "$(${CLAUDE_PLUGIN_ROOT}/skills/sigma-api/scripts/get-token.sh)"
- Cursor / Codex / generic:
eval "$(bash <repo-root>/skills/sigma-api/scripts/get-token.sh)"
The script's interface:
| In (env) | Out (stdout) |
|---|
SIGMA_BASE_URL, SIGMA_CLIENT_ID, SIGMA_CLIENT_SECRET | A single line: export SIGMA_API_TOKEN=... |
Non-zero exit on missing env vars or token-exchange failure; error message goes to stderr.
Manual token exchange (inline fallback)
CREDENTIALS=$(printf '%s:%s' "$SIGMA_CLIENT_ID" "$SIGMA_CLIENT_SECRET" | base64)
export SIGMA_API_TOKEN=$(curl -sf -X POST \
-H "Authorization: Basic ${CREDENTIALS}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
"$SIGMA_BASE_URL/v2/auth/token" \
| jq -r '.access_token')
[ -z "$SIGMA_API_TOKEN" ] || [ "$SIGMA_API_TOKEN" = "null" ] && { echo "Token exchange failed" >&2; exit 1; }
Step 3 — Verify the Token
GET /v2/whoami is the canonical sanity check that the token is valid and the base URL is correct — use it after each token exchange and any time a later call's response is suspect.
curl -sf -H "Authorization: Bearer $SIGMA_API_TOKEN" \
"$SIGMA_BASE_URL/v2/whoami" | jq .
The response includes userId, organizationId, and accountType.
Token Expiry
Tokens last about an hour. Re-eval the helper (or repeat the manual exchange) to refresh. For long-running sessions, it's fine to refresh at the top of each phase of work.
Interpreting HTTP Status Codes
- 2xx. Success.
- 401 Unauthorized. The token is missing, expired, or otherwise not accepted. Re-run the token exchange.
- 403 Forbidden. The credentials authenticated, but the caller isn't permitted to make this request.
- 404 Not Found. Wrong path, wrong
SIGMA_BASE_URL for the user's cloud, or the resource doesn't exist.
- 5xx. Server-side error. Retry with backoff.
Security Notes
- Never echo
$SIGMA_API_TOKEN, $SIGMA_CLIENT_SECRET, or any other secret to logs the user can share.
- Don't write secrets to files inside the workspace.
- Treat the bearer token like a password — only pass it via the
Authorization header, never on a query string.
