API keys

Create keys to drive oyehello from your own code.

An API key is how your own software talks to oyehello. Anything you can do by clicking around the console - launch a call, pull the results of a campaign, add contacts, list your numbers - you can also do from a script, a backend service, or a scheduled job. The key is the password that proves those requests are really coming from your workspace.

You don’t need to be a hardcore engineer to use one. If you (or someone on your team) can copy a value into an environment variable and make an HTTP request, you can build on oyehello. This page is the console side of the story: how to create a key, choose what it’s allowed to do, and keep it safe. When you’re ready to actually write code - the endpoints, the request formats, example calls - that lives in the API reference.

Who can do this? Only a workspace owner or admin can see or manage API keys. Regular members never touch them - which is deliberate, because a key is a powerful credential.

What a key is for

Think of your API key as a stand-in for you, but for machines. When your backend sends a request carrying the key, oyehello treats it exactly as if your workspace made that request itself - subject to whatever the key is allowed to do (more on that under Scopes).

Common reasons teams reach for the API:

  • Trigger calls from your own system - a customer signs up, your app fires a call, no human involved.
  • Sync results back to your database - pull call outcomes and dispositions on a schedule instead of exporting CSVs.
  • Manage contacts and campaigns programmatically - keep your calling lists in step with your CRM automatically.

Everything runs against the same workspace and the same wallet as the console, so there’s no separate account to fund or reconcile. See Billing & wallet for how usage is charged.

Create a key

Go to Account → API keys and click New key. You’ll fill in two things.

Key name

A label for you and your team - it’s never sent anywhere or seen by callers. Its whole job is to help you recognise the key later, especially the day you need to revoke one in a hurry.

  • Tip: name it after where it runs, not what it does - “Production backend”, “Zapier integration”, “Nightly sync job”. When something leaks or a service is retired, you’ll know exactly which key to kill without guessing.

Scopes

The permissions this key carries - a checklist of what it’s allowed to touch. You’ll see a grid of resources (Agents, Calls, Campaigns, Contacts, Numbers), each with a Read and a Write box. Tick only the ones this key genuinely needs. We cover how to think about this in Scopes just below.

Once you hit Create key, the key is generated and shown to you once - see The key is shown only once. Copy it, store it safely, and you’re done.

Keys look like ohk_live_… - the ohk_live_ prefix tells you at a glance it’s a real oyehello key that works against live data. Treat everything after it as a password.

Scopes (least-privilege)

A key can only ever do what its scopes allow - nothing more. If a key doesn’t have calls:write, then even if it’s stolen, whoever holds it cannot place a call. This is your single biggest safety lever, so it’s worth understanding.

Each scope is written as <resource>:<action> - the thing, then what you can do to it:

  • agents:read / agents:write - view your agents / create and edit them
  • calls:read / calls:write - view call results / place calls
  • campaigns:read / campaigns:write - view campaigns / create and manage them
  • contacts:read / contacts:write - view contacts / add and update them
  • numbers:read / numbers:write - view your phone numbers / manage them

The rule of thumb: give a key the narrowest set of scopes that lets it do its one job. A dashboard that only displays call results needs calls:read and nothing else - hand it calls:write and you’ve created a key that could rack up a phone bill for no reason.

  • Good: a reporting tool → calls:read, campaigns:read.
  • Good: a service that fires calls when users sign up → calls:write (plus contacts:write if it also adds the contact first).
  • Avoid: ticking every box “to be safe.” That’s the opposite of safe - it means one leaked key can do everything.

If a key ever needs more permissions later, don’t stretch an existing one - create a fresh key with exactly the scopes it needs. The full list of scopes and which endpoints each one unlocks is in the Scopes reference.

The key is shown only once

This is the one thing not to skim. When you create a key, oyehello shows you the full secret value exactly once, on the confirmation screen. We store only a scrambled fingerprint of it on our side - we cannot show it to you again, even if you ask support. That’s a security feature, not an oversight: it means a leak of our database still can’t hand anyone your working keys.

So on that screen:

  1. Hit Copy (or Download to save it as a text file) before you close the dialog.
  2. Paste it straight into a secret manager or an environment variable - the same place you’d keep a database password.
  3. Never put it in front-end/browser code, a mobile app, a screenshot, a Slack message, or a Git repository. Anywhere a key can be read by someone who shouldn’t have it, assume it will be.

Lost it? Don’t panic and don’t hunt for it - you won’t find it. Just revoke the key and create a new one. It takes ten seconds.

After creation, the console only ever shows a masked version (like ohk_live_••••a1b2) alongside when it was created and last used - enough to identify it, never enough to use it.

Rotate & revoke

Keys aren’t forever, and that’s healthy.

  • Revoke a key the instant you suspect it’s exposed - a laptop goes missing, a repo went public, a contractor leaves. Open Account → API keys, find the key by its name, and revoke it. Revocation is immediate: the next request carrying that key is rejected, so anything still using it stops working right away. That’s the point - you’re slamming a door.
  • Rotate keys periodically even when nothing’s wrong, as plain good hygiene. The smooth way to do it with zero downtime: create the new key first, switch your service over to it, confirm everything still works, then revoke the old one.

Because you named your keys after where they run, revoking the right one is a quick, confident click rather than a nervous guess. (This is why the naming tip earlier matters.)

Rate limits

To keep everyone’s calls flowing and to stop a runaway script from doing damage, the endpoints that spend money - placing a call - are capped at 60 requests per minute, per key. That’s a generous ceiling for normal use; you’d have to be firing calls in a tight loop to hit it.

If you do go over, the API replies with an HTTP 429 (“too many requests”) and a Retry-After header telling you how many seconds to wait. The fix in your code is simple: when you see a 429, pause for that many seconds and try again.

  • Tip: if you’re launching a big batch, prefer a campaign (which paces the calls for you) over hammering the place-a-call endpoint yourself. See Campaigns.

Read-only endpoints are far more relaxed. The precise, up-to-date limits and headers are documented in Rate limits.

Track usage

Every request is counted against the key that made it, so you can see consumption from day one. In the keys list, each key shows when it was created and when it was last used - a quick way to spot a key nobody’s touched in months (a good candidate to revoke) or confirm a new integration is actually live. Click into a key for a fuller usage breakdown.

All of it is billed against your workspace’s single wallet, exactly like console usage - there’s no separate API meter to watch. Details in Billing & wallet.

Where the code lives

This page got you a key and taught you how to look after it. The actual building - how to send the key, what to call, and what comes back - is in the developer docs:

Next: Compliance & data →