## TL;DR

Throw away the example key and rebuild the validation logic against real issued keys. Docs examples use placeholder formats like a short readable string; real keys have different prefixes, lengths, and character sets.

Never write parsing code against example values: get a real key from the provider's dashboard first, even a test-mode one, and validate against that.

## Verbatim query

```text
agent tested with the docs' example API key  -  the example key format didn't match real keys and the validation logic was wrong
```

## Steps

1. Get a real key to compare
   Create a test-mode key in the provider dashboard.
   Diff its format against the example key: prefix, length, charset, separators.
   Expected: You can list exactly how the real key format differs from the example.

2. Find everything built on the example
   Search the codebase for the example key string and for any regex or length check derived from it.
   Include client-side pre-validation and any key-parsing helpers.
   Expected: Every place that assumed the example format is identified.

3. Rewrite validation around real keys
   Base prefix checks, length checks, and parsing on the real format.
   Keep it lenient: validate structure, not exact length, since providers rotate formats.
   Expected: Real keys pass validation; the example-format assumptions are gone.

4. Delete the example key from the repo
   Remove the docs example key from code, tests, and fixtures.
   Replace test fixtures with obviously-fake keys in the real format.
   Expected: No occurrence of the example key remains in the codebase.

5. Verify with a real call
   Run the auth flow with the real test key end to end.
   Confirm key parsing, header building, and the 2xx response.
   Expected: A real key authenticates successfully through the fixed code.

## Use this when

- Key validation or parsing was written against the docs' example key
- Real keys fail client-side validation that the example key passed
- Auth works with curl but the generated client's key handling rejects real keys

## Not for this skill when

- Real keys are rejected by the API itself - that is a provisioning or scope problem
- The example key was never used in code - then it is just a docs curiosity
- Keys work but calls 403 - that is permissions, not key format

## Variant phrasings

### example API key format wrong
Docs examples are illustrative placeholders; their format is decoration, not specification.

### tested with docs example key
Anything validated against an example value is validated against fiction.

### real keys fail validation
When real keys fail but the example passes, the validation was built on the wrong reference.

## Why it happens

Docs examples are designed to be readable, not realistic: short, pronounceable, obviously fake. Real keys are long, prefixed, and charset-constrained. The agent treated the example as a format specification and wrote validation logic against it, so real keys - which look nothing like the example - fail the client's own checks before ever reaching the API. The example is documentation, not a test fixture.

## Edge cases

- Some providers issue different formats for test vs live keys - validate against both
- Example keys sometimes appear in provider SDKs too; audit vendored code, not just your own
- If the provider rotates key formats, keep validation structural and loose so the next rotation does not break you

## Provenance

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