Set your one-time-code defaults

Choose how WA.cr sends one-time codes for your workspace — which channels it tries and in what order, how long a code is, how long it lasts and how many wrong tries you allow. Owners can also let an API key read a generated code back.

Every one-time code your app asks for runs under your workspace's defaults unless the request says otherwise. You set them once, in the console, at Developers → One-time codes.

Where they are

Open Developers from the sidebar and scroll past your API keys and OAuth clients. The One-time codes card is at the bottom.

You need the Manage API keys & developer settings permission to see it — the same one that lets you create a key. One setting on the card needs more than that, and it is covered further down.

What you can set

Setting	What it does	Allowed
Delivery order	Which channels WA.cr tries, top to bottom	at least one
Code length	How many digits the code has	4–8
Valid for	How long the code works before it expires	60–900 seconds
Attempts	How many wrong tries before the code is dead	3–10

Delivery order is an order, not a set

The list is walked from the top. The next channel is only tried when the one above refuses the code outright — a wrong-looking number, a channel you haven't connected, a provider that rejects the send.

A code that was accepted and never turned up does not fall through to the next channel. From WA.cr's side, a message WhatsApp took and the handset never showed looks exactly like a code that arrived and is being typed in. Waiting to tell them apart would mean holding your API call open for a delivery report that lands seconds — sometimes minutes — later.

Use the arrows to re-order, and the tick-boxes underneath to add or remove a channel. A channel you switch on is added at the bottom, because position is the whole meaning of the list.

Today WA.cr sends codes over WhatsApp and email. SMS and voice appear in the list and are refused until those channels launch.

A request can always override you

These are defaults, not limits. A single API call can name its own channels or its own code length, and what it asks for wins for that call only. The card is what happens when it doesn't ask.

Your own settings, or the platform's

A brand-new workspace has no settings of its own — it runs on WA.cr's defaults, and the card says so. Saving anything gives your workspace its own copy, and Reset to defaults hands it back.

Those two states are not the same thing, even when the numbers look identical. Your settings are stored and replaced as one whole document, never merged field by field. If we merged them, a workspace that chose 4-digit codes and a platform that later moved the default expiry would end up on a combination nobody picked. So "no settings" genuinely means "whatever WA.cr's default is today", and it moves when that moves.

Letting a key read the code back

By default, WA.cr generates a code, delivers it, and never gives it to you. Only a hash of it is stored, and POST /v1/otp/{id}/verify is the only way to check it.

If your app needs the code itself — to show it on your own screen, or to send it through a channel of your own — that takes two permissions, not one:

the API key or OAuth client holds the otp:reveal scope, and
Allow keys to reveal generated codes is switched on for the workspace.

Both, because handing a plaintext code back over the internet is the first thing of its kind in WA.cr. The key says yes and the workspace says yes. With the scope but not the switch, the API answers 403 reveal_disabled, and the otp:reveal tick-box stays greyed out when you create a key.

Only an owner can move it

Anyone who can manage developer settings can edit the rest of the card. Allow keys to reveal generated codes can only be changed by a workspace owner — for everyone else it shows switched off and greyed, with the reason underneath. If you need it and you're not an owner, ask one; nothing else on the card is blocked for you.

That holds in both directions. Switching it back off is as much a change to your workspace's consent as switching it on, so an owner does that too.

Every change is written to your audit log, and so is every code that is actually revealed.

One thing to know about Reset to defaults. Clearing your settings hands the workspace back to WA.cr's defaults — including this switch. If the platform default ever allows disclosure, a reset could switch it on for you without the setting being touched directly. That is why Reset to defaults also needs an owner whenever it would move it.

If the card isn't there

Two reasons, and they look different:

The card shows but the form is greyed, with a line about your plan. One-time codes aren't part of your current plan. The card tells you what to do about it.
There's no card at all. One-time codes aren't switched on for your account yet.