Module · Integrations and channels
API keys and OAuth: who has to click
Lesson 30 of 40 · 5 min
Every integration in the product is connected in one of two ways, and the difference between them has almost nothing to do with technology and everything to do with how long a client takes to go live.
| How it connects | How many | What it costs the client |
|---|---|---|
| API key | 55 | Somebody fetches a string and sends it to you. Can be delegated, done at any hour, and chased. |
| OAuth | 12 | A specific person signs in and grants access, live. Cannot be delegated to somebody without the permission. |
API key
- How many
55- What it costs the client
- Somebody fetches a string and sends it to you. Can be delegated, done at any hour, and chased.
OAuth
- How many
12- What it costs the client
- A specific person signs in and grants access, live. Cannot be delegated to somebody without the permission.
Why the smaller number is the bigger problem
An API key is asynchronous. You ask for it on Monday, somebody in their team digs it out on Wednesday, you paste it in on Wednesday evening. Nobody has to meet. If the first person cannot find it, they forward your email to somebody who can.
OAuth is a moment. Somebody has to be at a screen, signed in to the right account, with permission to grant access — and if the person on the call is not that person, the call ends with nothing. That is how a fifteen-second task becomes three weeks: not because it is hard, but because it needs a calendar.
Ask “who owns the ad account?” in the first meeting, not the fourth. The answer is often an agency, a founder who has left, or a personal account belonging to somebody's cousin. You want to discover that while you are still scoping, because it is the single commonest reason a go-live slips.
The four a client has to supply, by kind
| What they must supply | How | What to ask for |
|---|---|---|
api_key | 3 values from their provider | |
| Telephony | api_key | 2 values, including the number itself |
| Calendar | oauth | Whoever's diary the meetings go in, signed in |
| Ad account | oauth | Whoever administers the ad account, signed in |
- How
api_key- What to ask for
- 3 values from their provider
Telephony
- How
api_key- What to ask for
- 2 values, including the number itself
Calendar
- How
oauth- What to ask for
- Whoever's diary the meetings go in, signed in
Ad account
- How
oauth- What to ask for
- Whoever administers the ad account, signed in
That table is your go-live plan, in the order you should run it. Start the two API-key ones immediately, because they are somebody else's queue and the clock starts when you ask. Book the two OAuth ones as a single twenty-minute call with the right two people in it.
What a key actually is, and how to talk about it
A client will ask whether handing over a key is safe, and it is a fair question. The honest answer has three parts, and none of them is “trust us”:
- It is stored encrypted and never shown back to anybody, including you.
- It is scoped to whatever the provider scoped it to — they can issue a key that can only send WhatsApp messages, and they should.
- It can be revoked by them, at their end, without asking you. That is the sentence that ends the conversation, and it is true of OAuth too.
Never take a credential over WhatsApp or email if you can avoid it, and never ask a client to send you a password. You are asking for an API key, which is not a password and does not need to be treated like one — but the moment you behave casually about it, a sensible client stops trusting the rest of your process.
The one that is neither
WhatsApp is technically an api_key integration, and practically it is neither of these two things — because before there is any credential at all, the client needs a WhatsApp Business account, a verified business, and a number that is not already on consumer WhatsApp. That is a process with a queue at the other end of it, measured in days rather than minutes, and it is nobody's fault when it takes them.
Start it first, whatever else you do. It is the longest pole in almost every deployment and the one clients most often assume is instant, because they already use WhatsApp all day.
Change one thing — write the ask
- Pick a real client. Write the email you would send asking for the two API-key credentials, naming exactly which values you need.
- Now write the calendar invitation for the OAuth call, and name the two roles who must be on it.
- Check your email against the catalogue: does it ask for every required field, or will you be going back a second time?
- Going back a second time is the thing to avoid. It is not a technical failure and a client remembers it as one.
Try it
- Find an integration in the list whose auth method surprises you, and work out what that means for who you would need in the room.
- Decide what you would do if a client refuses to hand over an ad account. There is a real answer, and Telling Meta which leads were worth it is what they lose.
Next: What each channel needs before it can go live — the same four, channel by channel, with what actually has to be true before each can carry a live customer.