In short
- An API key identifies the app or agent making a request and ties every call to an account, its limits and its bill.
- Keys travel in a request header, usually Authorization: Bearer, rather than in the URL, where logs and browser history would keep them.
- A good key carries the least access the job needs, and often a spend limit and an expiry date, so a leaked key can do little harm.
- Rotate keys on a schedule and the moment one may have leaked, and revoke the keys you no longer use.
- One PrimaryAPI key reads every API in the catalog, from your code or your AI agent, and you only pay when data comes back.
How an API key works
When your code calls an API, it sends the key with the request. The API looks the key up, finds the account it belongs to, checks what the key may do, and then answers or refuses. The key is how the API knows whose limits apply and who pays.
A key is not quite a password. It belongs to a program rather than a person, it has no second factor, and it often lives for months. That is why a key should be allowed to do as little as possible, and be easy to replace.
A PrimaryAPI key looks like pa_live_ followed by random letters and digits. You send it in the Authorization header as a Bearer token, or in X-API-Key if your HTTP client makes Authorization awkward. Keys are never accepted in the URL, so they stay out of server logs.
API keys, tokens and OAuth
An API key stands for an app or a workspace and usually lasts until you replace it. An OAuth access token stands for a person who signed in and agreed to share something, such as their calendar, and expires quickly.
Use a key when your own server calls an API for your own account. Use OAuth when your app acts for other people and needs their permission.
Some platforms combine the two: you register an app, receive a client ID and a client secret, and exchange them for short-lived tokens on every session. Guides for those platforms talk about apps rather than keys for that reason.
Scopes and access levels
Most APIs let you limit what a key can do. The rule is least privilege: a key that only reads cannot delete, and a key that cannot spend cannot run up a bill.
Every PrimaryAPI key has one access level, picked when you create it:
- Run, the default: calls and prices APIs and reads results, but cannot see billing or manage keys. It suits production services and agents.
- View: reads the balance, usage and past requests, and can never spend. Give it to dashboards and monitoring.
- Full: everything a key can do, including creating, rotating and revoking other keys. Keep it for admin scripts.
- On top of its access, a key can carry its own spend limit in credits, per day, week or month or over its lifetime, and an expiry date. An agent with a capped key stops at the cap instead of draining the balance.
How to keep an API key secret
Treat a key like a password that never expires on its own. Most leaks are ordinary: a key pasted into a repository, a front-end bundle, a log line or a screenshot.
PrimaryAPI shows a new key once and keeps only a hash of it, so nobody, including us, can show it to you again. Copy it straight into your secrets manager.
- Keep keys on the server. Code that runs in a browser or a mobile app can be read by anyone who uses it.
- Read the key from an environment variable or a secrets manager, never from a file you commit.
- Never paste a key into a chat, a ticket or an AI prompt. Put it in the tool’s settings instead.
- Redact the Authorization and X-API-Key headers in your logs.
- Use one key per service, environment and agent, so you know which one leaked and replace only that one.
How to rotate or revoke an API key
Rotate keys on a regular schedule, and at once when one may have leaked or when someone who had it leaves. The safest switch has an overlap, so the new key works before the old one stops.
If you can redeploy at once, PrimaryAPI can also rotate a key in place: its id, name, limits and history stay, and the old secret stops working immediately.
- Create a second key with the same access level and spend limit.
- Deploy it everywhere the old key is used, and check that requests succeed.
- Revoke the old key. A revoked PrimaryAPI key stops working at once and stays in your list, marked revoked.
- Check your usage for calls you don’t recognise from before the switch.
One PrimaryAPI key for every kind of data
A PrimaryAPI key reads public data from social platforms, Google Maps places, company filings and validation checks, from one balance of credits. Each API’s page shows its price, and you only pay when data comes back.
AI agents use the same key through the MCP server or the SKILL.md file, and an agent with no key can mint a capped trial key on its own for a person to approve later.
To get one, create an account, open API keys in the dashboard and choose Create key. Keep the default run access unless the key needs more.
Try it with PrimaryAPI
One key for every API below, for your code and your AI agents. You only pay when data comes back.
- Email VerificationDeliverability verdict for one email address, with catch-all, disposable, role and free-provider signals and a confidence score1 credit / call
- Reddit SearchSearch Reddit posts across all subreddits by query, with sort order and time window, cursor paged2 credits / call
- Google Maps SearchSearch Google Maps for places matching a query in a free-text location and get up to 20 normalised places with rating, address, phone, website and coordinates2 credits / call
- YouTube TranscriptExisting captions of a YouTube video or Short as plain text plus timed segments, by URL or ID2 credits / call