Authentication
118 of the 135 operations need an API key. Two headers carry it, every plan starts free, and a refused credential says exactly why.
Two ways to send a key
Both headers carry the same key and both are canonical: neither is being retired. If you send both, X-API-Key wins. The scheme name is matched case-insensitively.
X-API-Key: <key>
The plain header. What the playground and the curl samples in this reference send.
cURL
curl -H "X-API-Key: your_api_key" \ https://api.gunspec.io/v1/firearmsAuthorization: Bearer <key>
What the generated SDKs and most HTTP clients send by default. The token is the same key.
cURL
curl -H "Authorization: Bearer your_api_key" \ https://api.gunspec.io/v1/firearmsSend a key only over TLS and only from server-side code; the Security page covers hygiene.
What needs a key
118 operations need a credential; 19 answer without one.
118 operations need a key
The whole catalog: firearms, search, compare, manufacturers, calibers, ammunition, statistics, and every account and seller endpoint. A keyless call is a 401, never a reduced response.
19 are open
Content, a shared collection, the two health probes, the spec itself and its Swagger UI: readable by anyone.
- GET
/v1/out/{clickId} - GET
/v1/ammunition/{id}/bullet.svg - GET
/v1/data/gaps - GET
/v1/data/tasks - GET
/v1/data/tasks/{taskKey} - GET
/v1/data/gaps/history - GET
/v1/changelog - GET
/v1/changelog/{id} - GET
/v1/notices - GET
/v1/sdk/verification - GET
/v1/examples/verification - GET
/v1/contract - GET
/v1/blog - GET
/v1/blog/{slug} - GET
/v1/collections/{shareId} - GET
/health - GET
/ready - GET
/openapi.json - GET
/docs
The last two are served by the API but are not operations in the spec; the health probes are, and answer 200 or 503 with no key.
What a key unlocks
A key carries its plan. The plan decides which endpoints answer, how many fields come back, how deep a list can be paged and how many requests a minute and a day are allowed.
- ExplorerFree. The list endpoints with a summary field set, five pages deep, hidden totals.
- BuilderFull specifications, search, compare, images and 3D model URLs, game stats.
- StudioEvery endpoint including the compatibility engine, webhooks, unlimited paging.
- EnterpriseStudio plus the seller listing, the highest limits, an SLA and dedicated support.
Creating, rotating and revoking keys
Keys live in your profile on the main site. A key is shown once at creation; store it then.
- 1Sign in on gunspec.io and open Profile, then API keys.
- 2Create a key per application or environment and name it so you know what to revoke later.
- 3Rotate on a schedule: create the new key, deploy it, then revoke the old one. Revocation is immediate.
- 4Disable a key to pause it without losing its name and history; a disabled key answers
401 KEY_DISABLED.
When a key is refused
A 401 is always about the credential, and error.reason names which problem. A 403 means the key is fine and the plan or account is not permitted; a new key does not change that.
AUTH_REQUIREDThis endpoint needs a credential and none was sent.KEY_MISSINGNo API key was sent.KEY_INVALIDThe API key is not one we issued, or it has been deleted.KEY_DISABLEDThe key was switched off by the account that owns it.KEY_EXPIREDThe key has passed its expiry date.
Trying it in the playground
Every endpoint page has a Try It console. Paste a key once and it is kept in this browser only, sent as X-API-Key on each request from the console, and never stored by us.