Create a Groq credential in the right project, verify it with a small request and keep it outside your code. These checks separate authentication from model permissions and billing access.

Before you start

Select the Groq organization and project that should own the experiment. The selected project determines the scope of newly generated credentials and the corresponding logs. Give each environment a recognizable project name. Official documentation.

Check whether the organization uses the Free or Developer plan. A key is not a promise of free or unlimited inference; plan features and billing controls must be reviewed separately. Official documentation.

Use a harmless test prompt and keep the initial payload small. A minimal working request is easier to compare with a later failure than an application call containing retrieval, tools and several optional parameters.

Step-by-step: create the key

  1. Sign in to Groq Console and select the intended project in the organization/project control.
  2. Open API Keys and start the create-key action. Use a name describing the application and environment.
  3. Save the revealed value in your secret store. Keep screenshots and support messages free of the secret.
  4. Confirm the key belongs to the expected project and record who is responsible for its use.

Changing the console’s project selection also changes which API Keys, logs and usage records you see. If a test seems absent from usage, first check that selection. Official documentation.

Before connecting the key to a worker, confirm that its application name and project are recognizable in the console. This makes a later usage investigation easier.

Set a spending limit / budget alerts

Paid-plan organization owners can configure Spend Limits in Settings, Billing, Limits. The spending limit applies across the organization’s keys; it is not a separate per-project budget. Official documentation.

Spend tracking can lag and work already in progress can complete. Keep an application budget margin instead of assuming the provider control stops at an exact final charge. Official documentation.

Decide who responds to an alert and what the application does if requests stop. A monitored queue should pause new work, preserve pending tasks and expose a useful diagnostic state. Do not let repeated retries become the fallback for every account rejection.

Verify the key: first call with cURL and Python

The REST request uses an Authorization bearer header. The native Groq Python client accepts the credential during initialization. These examples call Chat Completions. Official documentation.

curl --max-time 30 https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"Say hello."}],"max_completion_tokens":128}'
import os
from groq import Groq

client = Groq(api_key=os.environ["GROQ_API_KEY"], timeout=30.0)
response = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[{"role": "user", "content": "Explain one useful application of model APIs."}],
    max_completion_tokens=256,
)
print(response.choices[0].message.content)

The successful response contains choices and usage. This is a shape illustration with labelled values, not a captured completion:

{"choices":[{"message":{"role":"assistant","content":"<generated text>"}}],"usage":{"prompt_tokens":"<observed value>","completion_tokens":"<observed value>"}}

Inspect your real response before adding application logic. The output text can vary, while the key diagnostic questions are whether the requested model was accepted and whether the response is complete.

Where to put the key

Load GROQ_API_KEY from the process environment. When using another compatible client, explicitly choose the Groq base URL so the credential goes to the intended service. Official documentation.

Keep the secret on the server side of a website. Exclude local environment files from version control and verify that request logging omits Authorization. A copied notebook can expose values in saved output even if the source no longer contains them.

Common rejections

A forbidden response can reflect model policy rather than an invalid key. Groq exposes different codes for organization-level and project-level model blocks. Official documentation.

Authentication, malformed request and capacity rejections require different fixes. Preserve the status and response body from the baseline before changing credentials or parameters. Official documentation.

Use Groq error diagnosis or the Python walkthrough to narrow the failure.

Rotate and revoke

Create a replacement in the intended project, update the application’s secret configuration and verify its smallest known-working request. Revoke the old credential after legitimate users have migrated. If a credential was exposed, revoke promptly and inspect usage rather than keeping it alive for convenience.

Rotation does not override model permissions. Review organization and project policies so a credential change does not become an accidental access expansion. Official documentation.

Use the AI API cost calculator to turn the model and workload you are considering into an estimate.

Last verified · Source ↗

Frequently asked questions

Why is my new key associated with another project?
The selected project is used when generating credentials. Choose the intended project before creating a replacement. Official documentation.
What variable does the example use?
The example reads GROQ_API_KEY from the environment and supplies it to the Groq client. Official documentation.
Does another key bypass model restrictions?
No. Organization and project model policies apply to the request independently of which credential is used. Official documentation.
What should a support reproduction contain?
Include the endpoint, model identifier, sanitized request shape, status and redacted response. Exclude the credential and unrelated account details.
How do I check a replacement before revoking the old key?
Run the minimal known-working request, verify the intended project’s usage and confirm deployed processes read the new secret.

Sources

Last verified · Source ↗