Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phpaisdk/groq/llms.txt

Use this file to discover all available pages before exploring further.

Every request the Groq provider sends to the Groq API must be authenticated with an API key. The key is transmitted as an HTTP Authorization: Bearer header on each request — there is nothing extra to sign or refresh. This page covers how to obtain a key, how to supply it to the SDK, and how to handle it safely in production.

​
Obtaining an API Key

API keys are issued through the Groq developer console at console.groq.com. Every key begins with the prefix gsk-, making them easy to spot in logs, .env files, and code reviews.
1

Sign in to the Groq console

Navigate to console.groq.com and sign in or create a free account.
2

Create a new API key

Open API Keys in the left sidebar and click Create API Key. Give the key a descriptive name (e.g. my-app-production) so you can identify and rotate it later.
3

Copy the key immediately

The full key value is shown only once. Copy it to your password manager or secrets store before closing the modal.
4

Add the key to your environment

Add the key to your .env file or server environment — never paste it directly into source files.
.env
GROQ_API_KEY=gsk-your-api-key-here

​
Supplying the Key to the SDK

The provider accepts the API key through two channels. Both are equivalent — choose whichever fits your deployment model. 
# .env (loaded by phpdotenv or your framework's env loader)
GROQ_API_KEY=gsk-your-api-key-here
When you call Groq::create() without an apiKey key, GroqOptions::fromArray() reads the GROQ_API_KEY environment variable automatically. If neither source provides a value, the provider throws an exception at construction time — before any HTTP request is made — so misconfiguration surfaces immediately.

​
How the Key Is Sent

Internally, GroqOptions::authHeaders() builds the request headers on every call:
GroqOptions::authHeaders() — from source
public function authHeaders(): array
{
    return array_merge(['Authorization' => 'Bearer ' . $this->apiKey], $this->headers);
}
This means every outbound request carries: 
Authorization: Bearer gsk-your-api-key-here
Any additional entries in the headers array are merged in after the Authorization header. Because PHP’s array_merge lets later keys overwrite earlier ones, avoid including an Authorization key in your headers array — it would silently replace the auth header set by the SDK.

​
Merging Custom Headers Alongside Auth

Use the headers option when your infrastructure requires extra headers such as tracing IDs or organisation identifiers. They travel alongside the Authorization header on every request.
Custom headers example
use AiSdk\Groq;

Groq::create([
    'apiKey'  => $_ENV['GROQ_API_KEY'],
    'headers' => [
        'X-Request-ID' => uniqid('req-', true),
        'X-Org-ID'     => 'org-acme',
    ],
]);
The final request headers will contain both Authorization: Bearer gsk-... and your custom headers.

​
Best Practices

Never hardcode an API key directly in PHP source files or commit one to version control. If a key is exposed in a public repository, rotate it immediately from console.groq.com and audit your usage logs.
Add .env to your .gitignore so that local credential files are never accidentally staged. A .env.example file with placeholder values is safe to commit and helps new contributors understand which variables are required.
Key hygiene recommendations:
  • Use environment variables — load credentials with a library like vlucas/phpdotenv in development and use native environment injection (Docker secrets, AWS SSM Parameter Store, Kubernetes secrets) in production.
  • Prefer secrets managers in production — retrieve the key at runtime from a dedicated secrets store rather than baking it into container images or CI/CD environment files.
  • Scope keys by environment — use separate keys for development, staging, and production so a breach in one environment does not affect others.
  • Rotate keys regularly — treat API keys like passwords: rotate them on a schedule and immediately after any suspected exposure.
  • Monitor usage — the Groq console shows per-key usage metrics. Unexpectedly high usage can indicate a leaked key.

​
Validating Your Setup

Once your key is in place, run the snippet below to confirm the provider authenticates successfully. A valid response — even a short one — confirms the key is accepted.
Verify authentication
use AiSdk\Generate;
use AiSdk\Groq;

// Reads GROQ_API_KEY from the environment automatically
$result = Generate::text('Say "authenticated" and nothing else.')
    ->model(Groq::model('llama-3.3-70b-versatile'))
    ->run();

echo $result->text; // authenticated
If the key is missing or invalid, Groq returns a 401 Unauthorized response and the SDK throws an exception with the API’s error message, making the problem straightforward to diagnose.

Build docs developers (and LLMs) love

Get started for freeTalk to us