n4nAI
Open console →
API integrationHow-tocURL LLM API Cookbook

Testing API key auth with curl before writing code

Learn how to curl test api key authentication against LLM endpoints before writing code. Step-by-step CLI checks for bearer tokens, error cases, and live calls.

n4n Team4 min read857 words

Audio narration

Coming soon — every post will get a voice note here.

Before you wire API key handling into your application, a quick curl test api key authentication against the endpoint saves hours of debugging later. A single misplaced header or malformed token fails silently behind SDK abstractions. This guide walks through verifying credentials at the command line, step by step, so you know the auth layer works before any code depends on it.

Step 1: Export the key to an environment variable

Never paste secrets directly into a curl command in an interactive shell. The string lands in ~/.bash_history or ~/.zsh_history and persists after the session ends. Load it into the process environment instead, or read it interactively without echoing.

# Option A: export from a value you paste once
export LLM_API_KEY="sk-your-real-key-here"
# Confirm it is set without printing the full value
echo "${LLM_API_KEY:0:4}… (length: ${#LLM_API_KEY})"

# Option B: read silently (bash/zsh)
read -rsp "Paste API key: " LLM_API_KEY; echo
export LLM_API_KEY

If you must type the key interactively, disable history for the session first:

set +o history
export LLM_API_KEY="sk-your-real-key-here"
set -o history

The curl test api key authentication procedure relies on parameter expansion ($LLM_API_KEY) so the secret never appears in the command line arguments visible to ps or shell logs. Treat the variable as volatile; unset it when done (see Step 8).

Step 2: Determine the auth scheme from the provider docs

Most OpenAI-compatible LLM APIs expect a bearer token in the Authorization header:

Authorization: Bearer <key>

Some gateways or cloud proxies diverge. Azure OpenAI uses a plain api-key header. AWS Bedrock-style frontends may use x-api-key. Check the integration docs before guessing. If the spec says “OpenAI compatible”, assume bearer. A wrong header name returns 401 even with a valid key, which is why the isolated curl test api key authentication step matters—you eliminate the variable of SDK misconfiguration and confirm the contract directly.

Step 3: Send a minimal authenticated request

Hit the models list endpoint. It requires auth but does not consume tokens or trigger model inference, making it the cheapest possible check. Use -sS to silence progress but show errors, and -w to print the HTTP status separate from the body.

curl -sS -o /tmp/models.json -w "HTTP %{http_code}\n" \
  https://api.openai.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY"

For an OpenAI-compatible gateway such as n4n.ai, the same pattern works against its single endpoint that fronts 240+ models; append a routing directive header to target a specific backend during the test:

curl -sS -o /tmp/models.json -w "HTTP %{http_code}\n" \
  https://api.n4n.ai/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "x-routing: provider=anthropic"

A 200 written by the -w flag plus a populated /tmp/models.json confirms the credential is structurally valid and accepted. If you get 000 as the status, curl failed to connect—check the URL or proxy, not the key.

Step 4: Parse the success and failure responses

On success, the body is JSON with an object: "list" and a data array:

{
  "object": "list",
  "data": [
    { "id": "gpt-4o", "object": "model", "owned_by": "openai" }
  ]
}

On auth failure, you get a 401 with an error object:

{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Note the difference between 401 Unauthorized (auth missing/invalid) and 429 Too Many Requests (valid key, rate limited). The latter still proves the curl test api key authentication succeeded; the former means the token is rejected. Inspect response headers with -D - if you need rate-limit clues (x-ratelimit-remaining).

Step 5: Deliberately break the request to confirm the failure path

Engineers often verify only the happy path. Also test what happens with no header and with a garbage key. This confirms the server actually validates the token rather than returning public data.

# No auth header
curl -sS -o /dev/null -w "no-header: HTTP %{http_code}\n" https://api.openai.com/v1/models

# Wrong key
curl -sS -o /dev/null -w "bad-key: HTTP %{http_code}\n" \
  https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-garbage"

Expect both to return 401 (or 403). If the no-header call returns 200, the endpoint is unauthenticated—a finding worth escalating. Running these negative cases is part of a complete curl test api key authentication pass; it proves the gate is real.

Step 6: Run a real inference call with the verified key

A models list check proves auth but not that the key has quota or model access. Send a minimal chat completion with max_tokens low to avoid cost.

curl -sS -w "\nHTTP %{http_code}\n" \
  https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 5
  }'

A successful response includes a choices array and a usage block:

{
  "choices": [{"message": {"role": "assistant", "content": "pong"}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
}

This step closes the loop: the curl test api key authentication now covers both credential validity and permission scope. If this returns 403 with model_not_found, the key is fine but lacks access to that model ID—switch to a model listed in /v1/models.

Step 7: Capture the working invocation for code translation

Once the call succeeds, serialize the exact headers and body. Use curl -v to dump the sent headers if you need to mirror them precisely in a client. In Python, the equivalent using requests is straightforward:

import os, requests

resp = requests.post(
    "https://api.openai.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['LLM_API_KEY']}"},
    json={"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 5},
)
print(resp.status_code, resp.json())

If you used a routing header in Step 3, forward it identically. Gateways that honor client routing directives will pass the hint through; n4n.ai also forwards provider cache-control markers, so any cache_control fields in the body reach the upstream unchanged—but that only matters once your app sends them. The point here is that the verified curl command is now a executable spec for your code.

Step 8: Clean up the shell environment

After testing, drop the variable so it does not leak into later debugging sessions or subprocesses.

unset LLM_API_KEY
# Optionally start a clean subshell for further work
env -i bash --norc

If the key was exposed in any shared terminal, CI log, or screen recording, rotate it immediately via the provider dashboard. The discipline of the curl test api key authentication workflow is to validate safely, then erase the trace.

Verifying success

Success means three things: the models endpoint returns HTTP 200 with a JSON list; the chat completion returns HTTP 200 with a non-empty choices array; and the deliberate failure cases in Step 5 return 401. At that point, the auth layer is proven. You can move to writing client code with confidence that any later error is in request shape, retry logic, or business logic—not the key. Keep the working curl snippet in your repo as a smoke test; it is the fastest way to re-verify credentials after a rotation or environment change.

Tagscurlauthenticationapi-keyscli

Written by

n4n Team

The team building n4n — a single OpenAI-compatible API in front of 240+ models, with automatic fallback, load balancing and pay-per-token metering.

More from n4n Team →
API integrationBuilding a Postman collection from curl LLM examplesPractical guide to convert curl to Postman collection LLM API examples with ordered steps, runnable code, and verification tips for engineers.API integrationcurl one-liners for checking LLM API rate limit headersPractical curl rate limit headers one-liners to inspect LLM API throttling, quota, and reset times across OpenAI, Anthropic, and inference providers.API integrationDebugging LLM API errors with curl -vUse curl -v to debug LLM API errors by exposing raw HTTP requests, TLS issues, and provider responses—a practical how-to for engineers integrating models.API integrationPiping curl streaming output into jq for parsingStep-by-step guide to piping curl streaming output into jq for parsing LLM API Server-Sent Events: strip data prefixes, filter deltas, and test locally.API integrationSending images to a vision model with curlStep-by-step guide to a curl vision model image request: encode images, build OpenAI-compatible JSON, post with curl, and verify multimodal LLM responses.API integrationUploading files to an LLM API with curl multipart formsLearn how to perform a curl multipart file upload llm api request from CLI with step-by-step examples for vision, documents, and errors.

All curl llm api cookbook posts →