Migrate external authentication connection

POST 
/marketplace/external-auth/migration

Migrates an external authentication connection credentials (basic or oauth2) for a specific app and location. This endpoint validates the app configuration, stores credentials safely in CRM's native encrypted storage. With this the lifecycle of the token is managed by CRM.

Request

Version stringrequired

API Version

Available optionsv3

application/json

application/json

Body

Bodyrequired

typestringrequired
Type of authentication - basic or oauth2
Available optionsoauth2basic
locationIdstringrequired

Location ID

appIdstringrequired

App ID

appVersionIdstringrequired

App Version ID

accountIdstringrequired

Connection identifier

apiKeystring

API Key (supported when type is basic)

basicCredentialsobject

Basic auth credentials as key/value pairs (supported when type is basic). Keys are validated against the app version externalAuthConfig.fields.

accessTokenstring

Access token (required when type is oauth2)

refreshTokenstring

Refresh token. Omit only when the provider issues long-lived, non-refreshable tokens (e.g. TikTok Marketing API, ClickUp) and therefore never returns one. Callers are responsible for supplying it whenever their app has a refresh endpoint configured: the migration stores exactly what it is given and replaces any previously stored secret, so omitting a refresh token the connection needs will leave it unable to refresh once the access token expires. Must be a non-empty string when supplied — null is rejected.

expiryInnumber

Access token expiry time in milliseconds (optional for oauth2)

expiryAtnumber

Timestamp for access token expiry (optional for oauth2)

scopesstring[]

OAuth2 scopes (optional for oauth2)

displayNamestring

Display name for the connection (optional, defaults to accountId)

emailstring

Account email metadata for the migrated connection

identitySourcestring
Source of the account identity metadata
Available optionsprovidermanual
isDefaultboolean

Whether this is the default connection for the location (optional, defaults to false)

Example (auto)

{
  "type": "oauth2",
  "locationId": "location_12345",
  "appId": "507f1f77bcf86cd799439011",
  "appVersionId": "507f1f77bcf86cd799439012",
  "accountId": "my-connection-identifier",
  "apiKey": "sk_test_1234567890",
  "basicCredentials": {
    "email": "[email protected]",
    "password": "p@ssw0rd"
  },
  "accessToken": "ya29.a0AfH6SMBx...",
  "refreshToken": "1//0gHq5F...",
  "expiryIn": 3600000,
  "expiryAt": 1735689600000,
  "scopes": [
    "contacts.readonly",
    "contacts.write"
  ],
  "displayName": "My Connection Display Name",
  "email": "[email protected]",
  "identitySource": "manual",
  "isDefault": false
}

application/json

Connection migrated successfully

application/json

Schema

Schema

successbooleanrequired

Indicates if the migration was successful

identifierstringrequired

Unique identifier for the migrated connection

messagestring

Message describing the result

Example (auto)

{
  "success": true,
  "identifier": "migration_12345",
  "message": "Connection migrated successfully"
}