Skip to main content

Integration

The Integration service provides CRUD capabilities for integration templates and integration instances (UserKey). It wraps the cloud API (tcb 2018-06-08), and every request carries Business='integration'.

Access it via manager.integration, for example:

const { integration } = new CloudBase({
    secretId: 'Your SecretId',
    secretKey: 'Your SecretKey',
    envId: 'Your envId' // Cloud Development environment ID, available in the Tencent Cloud Base console
})
Note

The SDK supports two modes:

  • Pass-through mode: Pass the ext JSON string directly (encrypt sensitive fields yourself), and the SDK forwards it as-is to the cloud API.
  • Auto-encryption mode: Pass envVariables as plaintext key-value pairs, and the SDK automatically identifies the password fields in the template, retrieves the encryption key from QiCaiShi, performs AES-256-CBC encryption, and assembles the ext string.

listTemplates​

1. Description​

Function: Get the list of integration templates (UserKey templates)

Declaration: listTemplates(params?: IListTemplatesParams): Promise<IGetUserKeyTemplateListResult>

2. Input Parameters​

IListTemplatesParams​

FieldRequiredTypeDescription
offsetNoNumberOffset, default 0
limitNoNumberLimit, default 100
authTypeCodeNoStringFilter by auth type code
authTypeNameNoStringFilter by auth type name
businessNoStringBusiness type; pass integration for the integration center

3. Response​

IGetUserKeyTemplateListResult​

FieldRequiredTypeDescription
RequestIdNoStringUnique request ID
TotalCountYesNumberTotal templates
KeyTemplateListYesArray<IUserKeyTemplate>Template list

IUserKeyTemplate​

FieldRequiredTypeDescription
AuthTypeCodeYesStringAuth type code (template key)
AuthTypeNameYesStringAuth type name (template display name)
ExtYesStringTemplate dynamic info as JSON string, includes fields definitions
AuthURLNoStringAuth URL (for OAuth-type templates)
IconNoStringTemplate icon
StateNoStringStatus
RedirectURINoStringRedirect URI

4. Example​

const res = await integration.listTemplates({
    limit: 20,
    business: 'integration'
})
console.log(res.KeyTemplateList)

listUserKeys​

1. Description​

Function: Get the list of integration instances (UserKey)

Declaration: listUserKeys(params?: IListUserKeysParams): Promise<IGetUserKeyListResult>

2. Input Parameters​

IListUserKeysParams​

FieldRequiredTypeDescription
nameNoStringFilter by name (fuzzy match)
authTypeCodeNoStringFilter by auth type code
offsetNoNumberOffset, default 0
limitNoNumberLimit, default 100
businessNoStringBusiness type; pass integration for the integration center

3. Response​

IGetUserKeyListResult​

FieldRequiredTypeDescription
RequestIdNoStringUnique request ID
TotalCountYesNumberTotal instances
UserKeyListYesArray<IUserKeyInfo>Instance list

IUserKeyInfo​

FieldRequiredTypeDescription
NameYesStringIntegration instance name
KeyIDYesStringIntegration instance ID (unique)
AuthTypeCodeYesStringAuth type code
AuthTypeNameYesStringAuth type name
ExtYesStringConfig JSON string (contains encrypted sensitive values)
DescriptionNoStringDescription
StatusNoStringStatus
TicketIDNoStringOAuth-type auth ticket id
DemoCodeFunctionNameNoStringBound sample code cloud function name
BindServiceListNoObjectBound service list (grouped by Mcp / Apis / Other)
CreateAtNoStringCreation time (ISO 8601)
UpdateAtNoStringUpdate time (ISO 8601)

4. Example​

const res = await integration.listUserKeys({
    name: 'my-key',
    business: 'integration'
})
console.log(res.UserKeyList)

getUserKey​

1. Description​

Function: Get a single integration instance

Declaration: getUserKey(params: IGetUserKeyParams): Promise<IGetOneUserKeyResult>

2. Input Parameters​

IGetUserKeyParams​

FieldRequiredTypeDescription
keyIdYesStringIntegration instance ID
needPwdNoBooleanWhen true, returns the encrypted value of sensitive fields; default false
decryptPwdNoBooleanWhen true, the SDK automatically decrypts the password field and returns plaintext (requires needPwd=true)
businessNoStringBusiness type; pass integration for the integration center

3. Response​

IGetOneUserKeyResult​

FieldRequiredTypeDescription
RequestIdNoStringUnique request ID
UserKeyInfoYesIUserKeyInfoIntegration instance detail

See listUserKeys for the UserKeyInfo field definitions.

4. Example​

// Get instance details (without sensitive field values)
const res = await integration.getUserKey({
    keyId: 'my-key-id',
    business: 'integration'
})
console.log(res.UserKeyInfo)

// Get instance details and auto-decrypt sensitive fields
const resWithPwd = await integration.getUserKey({
    keyId: 'my-key-id',
    needPwd: true,
    decryptPwd: true,
    business: 'integration'
})
console.log(resWithPwd.UserKeyInfo)

createUserKey​

1. Description​

Function: Create an integration instance

Declaration: createUserKey(params: ICreateUserKeyParams): Promise<ICreateUserKeyResult>

Supports two parameter modes:

  • Pass-through mode: Pass ext (an encrypted JSON string), and the SDK forwards it to the cloud API as-is (backward compatible).
  • Auto-encryption mode: Pass envVariables (plaintext key-value pairs), and the SDK automatically identifies the password fields in the template, retrieves the encryption key from QiCaiShi, performs AES-256-CBC encryption, and assembles the ext string.
  • When both are provided, ext takes precedence.

2. Input Parameters​

ICreateUserKeyParams​

FieldRequiredTypeDescription
nameYesStringIntegration instance name
authTypeCodeYesStringAuth type code
descriptionNoStringDescription
extNoStringConfig JSON string (pass-through mode; contains encrypted sensitive values)
envVariablesNoRecord<string, string>Plaintext environment variables as key-value pairs (auto-encryption mode; SDK automatically encrypts password fields)
keyIdNoStringSpecify the instance ID (generated by backend if omitted)
ticketIdNoStringOAuth-type auth ticket id
demoCodeFunctionNameNoStringBound sample code cloud function name
runtimeConfigNoRecord<string, any>Agent cloud function config
businessNoStringBusiness type; pass integration for the integration center

3. Response​

ICreateUserKeyResult​

FieldRequiredTypeDescription
RequestIdNoStringUnique request ID
CreateResultYesNumberCreate result (0 means success)
DemoCodeFunctionNameNoStringSample code cloud function name

4. Example​

// Auto-encryption mode: pass plaintext envVariables, SDK automatically encrypts password fields
const res = await integration.createUserKey({
    name: 'my-wechat',
    authTypeCode: 'weixinoffiaccount',
    envVariables: {
        appId: 'wx1234567890',
        appsecret: 'your-plaintext-secret'  // Pass in plaintext, SDK auto-encrypts
    },
    business: 'integration'
})
console.log(res)

// Pass-through mode: pass pre-encrypted ext JSON string (backward compatible)
const res2 = await integration.createUserKey({
    name: 'my-payment',
    authTypeCode: 'weixinpaydc',
    ext: JSON.stringify({ appId: 'xxx', secret: 'encrypted-value' }),
    business: 'integration'
})
console.log(res2)

updateUserKey​

1. Description​

Function: Update an integration instance

Declaration: updateUserKey(params: IUpdateUserKeyParams): Promise<IUpdateUserKeyResult>

Supports two parameter modes:

  • Pass-through mode: Pass ext (the pre-merged JSON string), and the SDK forwards it to the cloud API as-is.
  • Auto-encryption mode: Pass envVariables (plaintext key-value pairs), and the SDK automatically merges them with the existing Ext and encrypts the password fields.
  • When both are provided, ext takes precedence. When neither is provided, the backend keeps the existing Ext unchanged.

2. Input Parameters​

IUpdateUserKeyParams​

FieldRequiredTypeDescription
keyIdYesStringIntegration instance ID
nameNoStringIntegration instance name
authTypeCodeNoStringAuth type code
descriptionNoStringDescription
extNoStringConfig JSON string (pass-through mode; contains encrypted sensitive values)
envVariablesNoRecord<string, string>Plaintext environment variables as key-value pairs (auto-encryption mode; SDK automatically merges with existing Ext and encrypts password fields)
demoCodeFunctionNameNoStringBound sample code cloud function name (used by bind-resource)
runtimeConfigNoRecord<string, any>Agent cloud function config
businessNoStringBusiness type; pass integration for the integration center

3. Response​

IUpdateUserKeyResult​

FieldRequiredTypeDescription
RequestIdNoStringUnique request ID
UpdateResultYesNumberUpdate result (0 means success)

4. Example​

// Auto-encryption mode: pass plaintext envVariables, SDK automatically merges with existing Ext and encrypts
const res = await integration.updateUserKey({
    keyId: 'my-key-id',
    description: 'updated description',
    envVariables: {
        appId: 'wx1234567890',
        appsecret: 'new-plaintext-secret'  // Pass in plaintext, SDK auto-merges and encrypts
    },
    business: 'integration'
})
console.log(res)

// Pass-through mode: pass pre-merged ext JSON string (backward compatible)
const res2 = await integration.updateUserKey({
    keyId: 'my-key-id',
    description: 'updated description',
    ext: JSON.stringify({ appId: 'xxx', secret: 'encrypted-value' }),
    business: 'integration'
})
console.log(res2)

deleteUserKey​

1. Description​

Function: Delete an integration instance

Declaration: deleteUserKey(params: IDeleteUserKeyParams): Promise<IDeleteUserKeyResult>

2. Input Parameters​

IDeleteUserKeyParams​

FieldRequiredTypeDescription
keyIdYesStringIntegration instance ID

3. Response​

IDeleteUserKeyResult​

FieldRequiredTypeDescription
RequestIdNoStringUnique request ID
DeleteResultYesNumberDelete result (0 means success)

4. Example​

const res = await integration.deleteUserKey({
    keyId: 'my-key-id'
})
console.log(res)