Groq Install & Auth

Overview

Install the official Groq SDK and configure API key authentication. Groq provides ultra-fast LLM inference on custom LPU hardware through an OpenAI-compatible REST API at api.groq.com/openai/v1/.

The workflow is four steps: install the SDK, mint an API key, export it as an environment variable, and verify the connection by listing models. Each step is summarized below; deep detail lives in references/.

Prerequisites

• Node.js 18+ or Python 3.8+
• Package manager (npm, pnpm, or pip)
• Groq account at console.groq.com
• API key from GroqCloud console (Settings > API Keys)

Instructions

Step 1: Install the SDK

bash
set -euo pipefail
# TypeScript / JavaScript
npm install groq-sdk

# Python
pip install groq

Step 2: Get Your API Key

1. Go to console.groq.com/keys
2. Click "Create API Key"
3. Copy the key (starts with gsk_)
4. Store it securely -- you cannot view it again

Step 3: Configure Environment

Add the .gitignore template before writing any .env file so a key can never be committed:

bash
# Set environment variable (recommended)
export GROQ_API_KEY="gsk_your_key_here"

# Or create .env file (add .env to .gitignore first)
echo 'GROQ_API_KEY=gsk_your_key_here' >> .env

Step 4: Verify the Connection

Run a short script that lists the models your key can access — a successful list proves authentication end-to-end. The essential TypeScript skeleton:

typescript
import Groq from "groq-sdk";

const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });
const models = await groq.models.list();
console.log(models.data.map((m) => m.id));

Full runnable TypeScript and Python verification scripts, with expected output: verification walkthrough.

Output

A successful setup produces:

• groq-sdk (Node) or groq (Python) installed in the project.
• GROQ_API_KEY available in the environment (or .env, with .env gitignored).
• A verification run that prints the accessible models, for example:

Connected! Available models:
  llama-3.3-70b-versatile (owned by Meta)
  llama-3.1-8b-instant (owned by Meta)

If the verification run prints a 401 instead of a model list, authentication failed — see Error Handling.

SDK Defaults & Key Formats

The SDK auto-reads GROQ_API_KEY from the environment when no apiKey is passed. Groq uses a single gsk_ key type with full API access (no read/write scopes). Constructor options (baseURL, maxRetries, timeout), the OpenAI-SDK compatibility path, and the key-format table are in the configuration reference.

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | 401 Invalid API Key | Key missing, revoked, or mistyped | Verify key at console.groq.com/keys | | MODULE_NOT_FOUND groq-sdk | SDK not installed | Run npm install groq-sdk | | ModuleNotFoundError: No module named 'groq' | Python SDK missing | Run pip install groq | | ENOTFOUND api.groq.com | Network/DNS issue | Check internet connectivity and firewall |

Extended diagnostics (checking the exported variable, .env loading, key rotation): troubleshooting reference.

Examples

Example 1 — Node project from scratch:

bash
npm install groq-sdk
export GROQ_API_KEY="gsk_your_key_here"
node --env-file=.env verify.mjs   # lists models → auth confirmed

Example 2 — Python project:

bash
pip install groq
export GROQ_API_KEY="gsk_your_key_here"
python verify.py                  # prints accessible models

Example 3 — reuse an existing OpenAI codebase: point the OpenAI SDK at Groq by overriding baseURL to https://api.groq.com/openai/v1 and passing your gsk_ key. See the configuration reference.

Complete, runnable versions of the verification scripts are in the verification walkthrough.

Resources

• Groq Quickstart
• Groq API Reference
• groq-sdk on npm
• groq-typescript on GitHub

Next Steps

After successful auth, proceed to the groq-hello-world skill to run your first chat completion. For SDK tuning (retries, timeouts, custom base URL), read the configuration reference.