Connect an adapter key to a partner

Gives an adapter the key it needs to act through a service the partner has an account with, for the widgets of the customers the partner manages. Take the adapterId and credentialKey from getPartnerAdapterConnections. Saving a key that is already connected replaces it.

What Widgetic does with it. The key is stored encrypted, bound to this partner, this adapter and this credential, so that a stored value cannot be moved to another. It is never returned, never logged and never shown to a visitor of a widget or to your customers. A server of Widgetic opens it for the one call a widget makes through the adapter, uses it to call the provider on the partner’s behalf, and discards it. To cut that off, remove the key here, or revoke it with the provider.

What is checked. That the adapter exists and takes this credential, that a partner may keep it (some are for an owner only) and that the text is one line of at most 2048 characters. Whether the provider accepts the key is not checked here: it shows the first time a widget uses it.

An address that has to be confirmed. Some credentials are not a key but the email address Widgetic sends a widget’s messages to (confirmation: email_code in getPartnerAdapterConnections). Saving one checks that it is one email address and emails a six-digit code to it; the answer says awaitingConfirmation: true, and nothing is sent to the address until the code is given back with confirmPartnerAdapterConnection. Saving the same address again before it is confirmed emails a new code (not sooner than a minute after the last); saving the address that is already confirmed changes nothing. If the code cannot be emailed, nothing is saved.

A widget whose adapter has no key connected, or whose address is not confirmed yet, is not charged and does not run that adapter: its visitors are told the feature is unavailable, and the partner is told once a day what to do.

This needs an API key with full access. The caller must be the person who administers the partner, or a Widgetic administrator. A retry is harmless: saving the same key twice only refreshes when it was set.

PUT /partners/{partnerId}/adapter-connections/{adapterId}/{credentialKey}

TypeScript SDK

TypeScript

import { Configuration, PartnersApi } from '@widgetic/api-sdk-ts';

const partnersApi = new PartnersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));

const { data: connection } = await partnersApi.setPartnerAdapterConnection({
  partnerId,
  adapterId: 'email',
  credentialKey: 'resendApiKey',
  setAdapterConnectionRequest: { credential: 'YOUR_PROVIDER_KEY' },
});
console.log(connection.connected, connection.updatedAt);

// An address a widget's messages are emailed to: a code is emailed to it, and it is used once the code is given back.
const { data: address } = await partnersApi.setPartnerAdapterConnection({
  partnerId,
  adapterId: 'email',
  credentialKey: 'recipient',
  setAdapterConnectionRequest: { credential: '[e-mail]' },
});
console.log(address.awaitingConfirmation);

200

{
  "success": true,
  "data": {
    "adapterId": "email",
    "adapterLabel": "Email",
    "credentialKey": "resendApiKey",
    "label": "Resend API key",
    "scope": "Example scope",
    "connected": true,
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "confirmation": "email_code",
    "awaitingConfirmation": true,
    "confirmedAt": "2026-01-15T09:30:00.000Z"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

partnerId · string<uuid> · required

The partner that keeps the key

adapterId · string · required

The adapter the key is for

Maximum string length: 40

credentialKey · string · required

The key's name within the adapter

Maximum string length: 40

Body

application/json

credential · string<password> · required · write-only

The key exactly as its provider gave it: one line of text, at most 2048 characters. It is stored encrypted and is never returned or logged. For a credential that is an email address (confirmation: email_code), write that one address, with nothing else

Maximum string length: 2048

Example:

"YOUR_PROVIDER_KEY"

Response

200

application/json

The key was saved

success · boolean · required

data · object · required

A key an adapter can take from an account, and whether the account has connected it. The key itself is never part of this: it is given once, when it is connected, and Widgetic keeps it encrypted.

Show child attributes

Example:

{
  "adapterId": "email",
  "adapterLabel": "Email",
  "credentialKey": "resendApiKey",
  "label": "Resend API key",
  "scope": "Example scope",
  "connected": true,
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "confirmation": "email_code",
  "awaitingConfirmation": true,
  "confirmedAt": "2026-01-15T09:30:00.000Z"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes