Skip to main content
Switchbord stores your WhatsApp provider credentials in an encrypted Vault so you can rotate them at any time without touching your deployment. You enter credentials through the product UI, and Switchbord handles storing them securely on the server. The raw values are never returned to the browser after you save them.

​
What credentials Switchbord stores

Switchbord manages three provider credentials for your WhatsApp connection:
  • Meta access token — used to authenticate all outbound message sends to the Meta Cloud API
  • Webhook signing secret — used to verify the signature of every inbound webhook payload from Meta
  • Meta verify token — used during the webhook challenge handshake when you register your endpoint with Meta
All three must be present and valid before Switchbord can send or receive WhatsApp messages.

​
Where to manage credentials

Switchbord has two places to work with credentials, depending on where you are in your setup:

Setup

The Setup page is for first-time configuration. Use it when you’re connecting a WhatsApp channel for the first time.

Settings → Provider

Settings → Provider is for ongoing credential rotation after your workspace is live.

​
Entering credentials for the first time

1

Open Setup

Navigate to /setup and sign in as the workspace owner. The setup checklist shows which credentials are configured and which are missing.
2

Enter your credentials

In the Provider section, enter your Meta access token, webhook signing secret, and Meta verify token. These values are sent directly to the server — they are not stored in your browser.
3

Save

Click Save. Switchbord writes each value to the Vault and immediately replaces the form fields with masked status indicators.
4

Validate your configuration

Click Validate configuration. Switchbord checks that your Meta access token is valid and returns the validation result. If the token is invalid, the product shows the Meta error code so you can identify the problem.

​
What the UI shows after you save

Once a credential is saved, Switchbord never returns the raw value to the browser. Instead, the Setup and Settings → Provider pages show:
  • Configured or Missing — whether a value is present in the Vault
  • Vault or Environment fallback — where the active value is coming from
  • Last validation status — whether the most recent validation succeeded or failed, and any Meta error code
  • Masked hints where available (for example, the last few characters of a token)
This design ensures that even if someone gains access to the product UI, they cannot extract the raw credential values.

​
Rotating credentials

When you need to rotate a token — for example, when a Meta access token is about to expire — you do not need to redeploy Switchbord.
1

Open Settings → Provider

Open Settings and select the Provider tab.
2

Enter the new value

Type the new token or secret into the corresponding field and click Save. The new value replaces the previous one in the Vault.
3

Run validation

Click Validate configuration to confirm the new token is accepted by Meta before treating the rotation as complete.
If your Meta access token expires or is revoked, outbound message sends will fail immediately. Rotate the token in Settings → Provider and re-validate as soon as possible to restore send capability.

​
Vault and environment fallback

For self-hosted deployments, Switchbord supports two sources for provider credentials:
  • Vault-stored credentials — values entered through the product UI and stored in the encrypted Vault. These are workspace-specific and take precedence over any environment-level values.
  • Environment fallback — values set at the deployment level (for example, in .env). These act as bootstrap defaults when no Vault value exists for a workspace.
Once you save a credential through the UI, that Vault value takes over for your workspace. Environment-level values remain as a fallback or emergency default, but Switchbord will not use them as long as a Vault entry exists.
Keep your server-level credentials set as a safety net, but treat the Vault as the authoritative source after your workspace is configured.

​
Access control

Only workspace owners, admins, and developers can write credentials through Setup or Settings. Regular members cannot view or modify provider credentials.