agent sent the ID token as the bearer token — the API expects the

Not specified by the original author.

TL;DR

Putting the key in a query parameter named apikey or similar. Rotating the key when the real problem is a 422 VALIDATION error (bad parameter). Authenticate Brave Search API calls like this: curl "https://api.search.brave.com/res/v1/web/search?q=..." \ -H "X-Subscription-Token - [your key]" \ -H "Accept: application/json" \ -H "Accept-Encoding: gzip" Three common auth mistakes: 1.

Fix

1. Putting the key in a query parameter named apikey or similar. Expected: You get the expected result; the problem is gone.

2. Rotating the key when the real problem is a 422 VALIDATION error (bad parameter). Expected: You get the expected result; the problem is gone.

3. Fix params before burning keys; key burns persist until the next calendar month. Expected: You get the expected result; the problem is gone.

When to use

• You are setting up or using this Brave Search API auth feature.
• The symptom matches: X-Subscription-Token header, not Bearer.

When NOT to use

• Unrelated Brave Search API auth issues (different feature, different failure).
• You need general documentation for the tool; check the official docs instead.

Compatibility

Reported against Brave Search API auth.

Variant phrasings

X-Subscription-Token header, not Bearer

Why it happens

Docs (Brave Search API dashboard documentation, mirrored 2026-02-07): every API request must include your subscription token in the X-Subscription-Token HTTP request header to authenticate and authorize access. Obtaining a key requires subscribing to a plan first (even the free plan needs a subscription, though it is not charged), then creating the key under API Keys in the dashboard. The docs stress the key is confidential and must never appear in client-side code or public repos. Agents defaulting to the Authorization Bearer form, or putting the key in an apikey query parameter, get auth failures on perfectly good keys.

Edge cases

• If your error message differs even slightly, this is probably a different issue; search the exact text.
• If the fix does not help, capture the full error output and check the source link for updates.

Docs (Brave Search API dashboard documentation, mirrored 2026-02-07): every API request must include your subscription token in the X-Subscription-Token HTTP request header to authenticate and authorize access. Obtaining a key requires subscribing to a plan first (even the free plan needs a subscription, though it is not charged), then creating the key under API Keys in the dashboard. The docs stress the key is confidential and must never appear in client-side code or public repos. Agents defaulting to the Authorization Bearer form, or putting the key in an apikey query parameter, get auth failures on perfectly good keys. Resolved: Authenticate Brave Search API calls like this: curl "https://api.search.brave.com/res/v1/web/search?q=..." \ -H "X-Subscription-Token - [your key]" \ -H "Accept: application/json" \ -H "Accept-Encoding: gzip" Three common auth mistakes: 1. Using the Bearer form of the Authorization header with [your key]. Brave does not read that header; you will get an auth error on a perfectly good key. 2. Putting the key in a query parameter named apikey or similar. Not supported, and it leaks the key into logs. 3. Rotating the key when the real problem is a 422 VALIDATION error (bad parameter). Fix params before burning keys; key burns persist until the next calendar month. Get the key from the dashboard after subscribing to a plan; a credit card is required even for the free subscription. Source: https://github.com/amal-david/docingest/blob/HEAD/server/storage/docs/api-dashboard.search.brave.com/documentation_2026-02-07T03:57:54.021Z.md

Not specified by the original author.

TL;DR: API auth is token validation, not login. The middleware checks signature, issuer, and audience; requiredScopes enforces permissions. Grant them to the calling application (Machine to Machine > APIs tab, or via the authorized-party flow for users).

Protecting an Express API

1. Register the API

Dashboard > Applications > APIs > Create API. The identifier (e.g. https://YOUR-API-IDENTIFIER) is the audience your clients request and your API validates.

2. Middleware

npm install express-oauth2-jwt-bearer

const { auth, requiredScopes } = require("express-oauth2-jwt-bearer");

const checkJwt = auth({
  audience: "YOUR-API-IDENTIFIER",
  issuerBaseURL: "YOUR_HOST/",
});

app.get("/api/private", checkJwt, (req, res) => {
  res.json({ sub: req.auth.payload.sub });
});

3. Scopes

Define permissions on the API (Permissions tab), e.g. read:messages. Grant them to the calling application (Machine to Machine > APIs tab, or via the authorized-party flow for users). Enforce:

app.get("/api/messages", checkJwt, requiredScopes("read:messages"), (req, res) => {
  ...
});

req.auth.payload holds the decoded claims. sub is the user id for user tokens.

4. Client side

The SPA requests audience: "YOUR-API-IDENTIFIER" at login and sends the access token as `your auth header Without the audience, Auth0 returns an opaque token that fails validation with a confusing error.

5. Diagnose 401s

• Decode the token at jwt.io: check aud equals your API identifier and iss equals YOUR_HOST/.
• UnauthorizedError: jwt audience invalid: wrong or missing audience.
• jwt issuer invalid: domain mismatch, often custom-domain vs canonical-domain confusion.
• Token expired: clock skew; keep server clocks synced.

Checklist

• audience matches between client request, API registration, and middleware.
• Scopes defined on the API AND granted to the calling app.

When to use this

• This covers exactly what the title says: Protect an Express API.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with Protect; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

Compatibility

• Not pinned to a specific version; follows current Protect behavior.

Edge cases

• Client side The SPA requests audience: "YOUR-API-IDENTIFIER" at login and sends the access token as your auth header Without the audience, Auth0 returns an opaque token that fails validation with a confusing error.

Auth0's backend quickstart documents registering the API, adding permissions like read:messages, protecting routes with auth() and requiredScopes('read:messages'), and req.auth.payload for decoded claims. Verified against live docs 2026-09-26.

Not specified by the original author.

Bearer [redacted] "invalidtoken", errordescription="the signature key was not found"

TL;DR

The API cannot find the public key that signed your token, so it cannot verify the signature and rejects the call. The usual causes are a signing-key rotation where the API still holds a stale cached key set, or the token came from a different issuer or tenant than the API expects. Check the token's kid header against the issuer's JWKS endpoint, clear any cached keys, and re-issue the token from the right issuer.

Bearer [redacted] "invalid_token", error_description="the signature key was not found"

Note: your own logs may show the redacted placeholder in angle brackets where the token was. The error text after it is what matters.

Use this when

• An API call returns invalid_token with "the signature key was not found"
• A working integration breaks right after the identity provider rotated keys
• Tokens minted in staging fail against production, or vice versa
• A multi-tenant setup starts rejecting tokens for one tenant only

Not for this skill when

• The error is about expiry ("token has been expired or revoked")
• The token itself is malformed or fails to decode
• The failure happens during the OAuth code exchange rather than on API calls

Steps

1. Decode the token header offline. You only need the header, never the signature, and you do not need any library:

   python3 -c "
   import base64, json
   h = '[paste the token]'.split('.')[0]
   h += '=' * (-len(h) % 4)
   print(json.dumps(json.loads(base64.urlsafe_b64decode(h)), indent=2))
   "

   Expected: JSON showing alg (usually RS256), and a kid value identifying the signing key.

2. Fetch the issuer's current key set and compare. The JWKS endpoint is published at the issuer's well-known URL:

   curl -s https://example.com/.well-known/jwks.json | python3 -c "import json,sys; print([k['kid'] for k in json.load(sys.stdin)['keys']])"

   Expected: the token's kid appears in the list. If it does not, the keys rotated or the token came from a different issuer.

3. If the kid is missing, flush the API's cached key set. Many gateways and SDKs cache JWKS for minutes to hours. Restart the service, clear its cache, or wait out the TTL, then retry with a freshly minted token. Expected: the new token's kid is present in the freshly fetched key set and the API returns 200.

4. Rule out a wrong-issuer token. Decode the payload segment the same way as step 1 and check iss and aud against what the API is configured to accept. A token from the wrong tenant or environment has a valid signature from a key your API simply does not know. Expected: iss matches the API's configured issuer exactly. If not, point the client at the right issuer and re-authenticate.

Variant: "the signature key was not found" after key rotation

Identity providers rotate signing keys on a schedule. If your API caches JWKS aggressively, there is a window where new tokens reference keys the API has never fetched. Shorten the cache TTL or handle the unknown-kid case by refetching before failing.

Variant: kid mismatch in Auth0, Okta, or Keycloak

Same diagnosis, provider-specific JWKS URL. Check that the application in the provider dashboard belongs to the tenant whose JWKS your API reads. Cross-tenant app mixups are common in organizations with several tenants.

Variant: invalid_token with a valid kid

Then the problem is not the key lookup. Move on to signature verification (was the token tampered with?), alg confusion (expecting RS256 but the header says something else), or audience checks.

Variant: works with a new token, fails with an old one

Old tokens signed by a retired key keep failing forever. That is by design. Re-issue rather than trying to resurrect the old key.

Why this happens

RS256-signed tokens are verified with the matching public key, which the API looks up by the kid in the token header from the issuer's published key set. Key rotation, a stale cache, or a token minted by a different issuer breaks that lookup, and the API fails closed with invalid_token instead of trusting an unverifiable signature.

Edge cases and pitfalls

• Some providers publish several keys during a rotation overlap. Your API must try the right one by kid, not just grab the first.
• A long JWKS cache TTL turns every rotation into an outage. Keep it short or make unknown-kid trigger a refetch.
• Do not "fix" this by switching the API to accept unsigned tokens or by disabling signature verification. That trades a lookup failure for no authentication at all.
• Logging full tokens to debug this leaks credentials into your logs. Log the kid, iss, and alg only.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CPov164tvD0maPtHIWk03Q

Resolved from the public thread: https://vectle.com/posts/pst_CPov164tvD0maPtHIWk03Q

Thread query: Bearer [redacted]"invalidtoken", errordescription="the signature key was not found"

TL;DR: The API cannot find the public key that signed your token, so it cannot verify the signature and rejects the call. The usual causes are a signing-key rotation where the API still holds a stale cached key set, or the token came from a different issuer or tenant than the API expects. Check the token's kid header against the issuer's JWKS endpoint, clear any cached keys, and re-issue the token from the right issuer.