Provider keys

Save a provider key

PUT/v1/workspaces/{workspaceId}/provider-keys/{provider}

Save the workspace's own key for a provider, replacing any saved one. The key is tried with its provider first. If the provider refuses it, the call answers 400 key_rejected with the provider's words, such as "Twilio said: …", and the saved key stays. Saved keys are encrypted, and a new one clears the old one's failure. It fails with 409 keys_not_enabled unless staff set the provider's check to run on the workspace's own keys (phone for twilio, email for neverbounce), and with 409 keys_unconfigured when PROVIDER_KEYS_SECRET isn't set on this deployment. Only the workspace owner can do this, and only from the app. See Owner-only and app-only.

curl -X PUT "$AYEFORM_API/v1/workspaces/$WORKSPACE_ID/provider-keys/$PROVIDER" \
  -H "Authorization: Bearer $AYEFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

200 Response

{
  "phone": {
    "source": "ayeform",
    "key": {
      "last4": "…",
      "accountSid": "…",
      "serviceSid": "…",
      "addedAt": 1790879400000,
      "failure": {
        "at": 1,
        "kind": "rejected",
        "message": "…"
      }
    }
  },
  "email": {
    "source": "ayeform",
    "key": {
      "last4": "…",
      "accountSid": "…",
      "serviceSid": "…",
      "addedAt": 1790879400000,
      "failure": {
        "at": 1,
        "kind": "rejected",
        "message": "…"
      }
    }
  },
  "telegramFree": false
}

Path parameters

workspaceIdstringrequired
The workspace's id. An API key can only use its own workspace.
providerstringrequired
The provider. twilio is Twilio Verify, which sends phone codes. neverbounce is NeverBounce, which checks email addresses.

Body

JSON, with Content-Type: application/json.

twilioobject
A Twilio Verify service's keys. Required when the provider is twilio, which otherwise answers 400 invalid.
Show 3 fieldsHide 3 fields
- accountSidstringrequired
  1–100 chars
- authTokenstringrequired
  1–200 chars
- serviceSidstringrequired
  The Twilio Verify service's SID.
  1–100 chars
neverbounceobject
The NeverBounce key. Required when the provider is neverbounce, which otherwise answers 400 invalid.
Show 1 fieldHide 1 field
- apiKeystringrequired
  1–200 chars

Response

Secrets are never returned: a key shows only its last 4 characters.

phoneobjectrequired
Phone codes (Twilio).
Show 2 fieldsHide 2 fields
- sourceenumrequired
  Whose keys the check runs on. ayeform uses Ayeform's keys and is charged in credits. own uses the workspace's own keys and house uses keys Ayeform set up for it, and neither is charged. With own and no key saved, or a key the provider refuses, the check is skipped and the response comes in not verified or not checked. It never falls back to Ayeform's keys.
  One of "ayeform", "own", "house"
- keyone of 2required
  The workspace's own saved key, shown whatever the source so the owner can still remove it after staff change the source. Null when none is saved. Keys Ayeform set up for the workspace are never shown.
  Show 2 optionsHide 2 options
  Option 1
  last4stringrequired
  The key's last 4 characters.
  addedAtnumberrequired
  When the key was saved, in milliseconds since the epoch.
  failureone of 2required
  The provider's last problem with the key. It clears once the key works.
  Show 2 optionsHide 2 options
  Option 1
  atnumberrequired
  kindenumrequired
  rejected means the provider refused the key, and checks are skipped until it's replaced. error means another error about the key's account or service, and checks are skipped while it lasts.
  One of "rejected", "error"
  messagestringrequired
  The provider's words.
  null
  accountSidstring
  Twilio only.
  serviceSidstring
  Twilio only.
  null
emailobjectrequired
Email checks (NeverBounce).
Show 2 fieldsHide 2 fields
- sourceenumrequired
  Whose keys the check runs on. ayeform uses Ayeform's keys and is charged in credits. own uses the workspace's own keys and house uses keys Ayeform set up for it, and neither is charged. With own and no key saved, or a key the provider refuses, the check is skipped and the response comes in not verified or not checked. It never falls back to Ayeform's keys.
  One of "ayeform", "own", "house"
- keyone of 2required
  The workspace's own saved key, shown whatever the source so the owner can still remove it after staff change the source. Null when none is saved. Keys Ayeform set up for the workspace are never shown.
  Show 2 optionsHide 2 options
  Option 1
  last4stringrequired
  The key's last 4 characters.
  addedAtnumberrequired
  When the key was saved, in milliseconds since the epoch.
  failureone of 2required
  The provider's last problem with the key. It clears once the key works.
  Show 2 optionsHide 2 options
  Option 1
  atnumberrequired
  kindenumrequired
  rejected means the provider refused the key, and checks are skipped until it's replaced. error means another error about the key's account or service, and checks are skipped while it lasts.
  One of "rejected", "error"
  messagestringrequired
  The provider's words.
  null
  accountSidstring
  Twilio only.
  serviceSidstring
  Twilio only.
  null
telegramFreebooleanrequired
Telegram checks are never charged.

Errors answer with a status and the error shape.