curl --request POST \
--url https://platform.versori.com/api/embedded/v1/activations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"userId": "<string>",
"integrationId": "<string>",
"connections": [
{
"templateId": "<string>",
"connectionId": "<string>"
}
],
"dynamicVariables": {}
}
'{
"id": "<string>",
"user": {
"id": "<string>",
"externalId": "<string>",
"displayName": "<string>",
"hubId": "<string>",
"primaryConnection": {
"id": "<string>",
"name": "<string>",
"credentials": {
"action": [
{
"id": "<string>",
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"schemeType": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"data": {},
"usages": [
{
"connection": {
"id": "<string>",
"name": "<string>",
"connector": {
"id": "<string>",
"organisationId": "<string>",
"name": "<string>",
"protocol": "http",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}
],
"errors": [
"<string>"
],
"expiresAt": "2023-11-07T05:31:56Z"
}
}
],
"trigger": [
{
"id": "<string>",
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"schemeType": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"data": {},
"usages": [
{
"connection": {
"id": "<string>",
"name": "<string>",
"connector": {
"id": "<string>",
"organisationId": "<string>",
"name": "<string>",
"protocol": "http",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}
],
"errors": [
"<string>"
],
"expiresAt": "2023-11-07T05:31:56Z"
}
}
]
},
"variables": [
{
"name": "<string>",
"value": "<string>"
}
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"hubId": "<string>",
"integration": {
"id": "<string>",
"name": "<string>",
"imageUrl": "<string>",
"description": "<string>",
"isDeployed": true,
"isActivated": true,
"variablesSchema": {}
}
}Activate Integration
ActivateIntegration activates an Integration for an End User. This is the final step in the activation process and will create the necessary connections and configurations to allow the Integration to run.
This endpoint can either reference existing connections or create new ones. Once these connections are resolved/created, if there are any missing connections to what the integration requires, an error will be returned.
curl --request POST \
--url https://platform.versori.com/api/embedded/v1/activations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"userId": "<string>",
"integrationId": "<string>",
"connections": [
{
"templateId": "<string>",
"connectionId": "<string>"
}
],
"dynamicVariables": {}
}
'{
"id": "<string>",
"user": {
"id": "<string>",
"externalId": "<string>",
"displayName": "<string>",
"hubId": "<string>",
"primaryConnection": {
"id": "<string>",
"name": "<string>",
"credentials": {
"action": [
{
"id": "<string>",
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"schemeType": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"data": {},
"usages": [
{
"connection": {
"id": "<string>",
"name": "<string>",
"connector": {
"id": "<string>",
"organisationId": "<string>",
"name": "<string>",
"protocol": "http",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}
],
"errors": [
"<string>"
],
"expiresAt": "2023-11-07T05:31:56Z"
}
}
],
"trigger": [
{
"id": "<string>",
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"schemeType": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"data": {},
"usages": [
{
"connection": {
"id": "<string>",
"name": "<string>",
"connector": {
"id": "<string>",
"organisationId": "<string>",
"name": "<string>",
"protocol": "http",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}
],
"errors": [
"<string>"
],
"expiresAt": "2023-11-07T05:31:56Z"
}
}
]
},
"variables": [
{
"name": "<string>",
"value": "<string>"
}
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
},
"hubId": "<string>",
"integration": {
"id": "<string>",
"name": "<string>",
"imageUrl": "<string>",
"description": "<string>",
"isDeployed": true,
"isActivated": true,
"variablesSchema": {}
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
ActivationCreate is the request payload to activate an Integration for End User
UserID references the user to activate the integration for, this may be their Versori identifier or their
external identifier, indicated by the userIdType field.
IntegrationID references the Integration that the activation is for.
Connections is a list of Activation Connections to create for this Activation. Each Activation Connection can either reference an existing underlying Connection, or a new Connection can be created.
ActivationConnectionCreate defines how an Activation Connection should be created. It may reference an existing Connection belonging to this Ens User, or a new Connection can be created.
ActivationConnectionCreateNew defines a new Connection to be used in an Activation
Dynamic variables can be used on an integration at run time. The user specifies the value of these variables when activating an integration. When an integration is created, the name and types of these variables can be defined.
Response
OK
Show child attributes
Show child attributes
ID is the Versori identifier for the user. Most APIs will not use this field but instead reference users by their externalId.
ExternalID is the identifier for the user as determined by the organisation. This typically should be the same as the user's ID on the Primary Connector for the Hub. Regardless of the value, it must be unique within the Hub.
DisplayName is an optional human-readable name for the user. If not set, the default is an empty string.
The hub ID to which the user belongs to.
PrimaryConnection is the connection that the user will use to authenticate to the primary connector.
Show child attributes
Show child attributes
ID is the unique identifier of the Connection. Typically this is only used internally and most (if not all)
public-facing APIs will use the name in combination with the Connector's id instead.
Name is the name of the Connection. This must be unique within the owning Connector.
ConnectionCredentials defines the Action and Trigger credentials for the owning Connector. If multiple credentials are defined for each type, they are applied to the request in the order they are defined. This is to enable Connectors which require both a user session token and an API key to be provided in the request.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
AuthSchemeConfig defines how a Connector implements the AuthScheme in order to fulfil its authentication requirements. This is purely the configuration and not the actual credential which is used to authenticate. The credential uses this configuration to determine how to authenticate.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
"none"ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
CredentialBase is the base type for all credentials. It contains the common properties which are shared across all credential types.
Show child attributes
Show child attributes
ID is the unique identifier of the Credential.
OrganisationID is the unique identifier of the Organisation which owns the Credential.
CredentialType denotes the type of the credential which determines what the Credential's data property will
contain.
- none: No credential is required to authenticate with the Connector.
- string: The credential is a string value, such as an API key or password.
- binary: The credential is a binary value, such as a private key, certificate or other file.
- basic-auth: The credential is a username and password to be used for basic authentication.
- oauth2-client: The credential is an OAuth2 client ID and secret to be used for OAuth2 authentication.
- oauth2-code: The credential is a temporary authorization code which will be exchanged for an oauth2-token.
- oauth2-password: The credential is an OAuth2 username and password with an optional client ID and secret to be used for OAuth2 authentication.
- oauth2-token: The credential is an OAuth2 access_token to be used for OAuth2 authentication.
- custom-function: The credential is a custom function which will be called to authenticate with the Connector.
- jwt-bearer: The credential is the JWT setup values to be used for generating a bearer token.
- certificate: The credential is a PEM encoded certificate, key and CA to be used for TLS client authentication.
none, string, binary, basic-auth, oauth2-client, oauth2-code, oauth2-password, oauth2-token, custom-function, certificate, jwt-bearer Name is the name of the Credential.
CredentialDataNone contains no data as no credential is required to authenticate with the Connector. It is used purely as a placeholder to implement a consistent interface across all CredentialType/AuthSchemeTypes.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
CredentialUsages is a list of references to the Connectors which are using this Credential. To aid performance, this field will only be defined for specific endpoints. An undefined property means that the usages have not been loaded, whereas an empty array indicates that the credential is not used by any connectors.
Show child attributes
Show child attributes
CredentialUsageConnection contains the information about an Connection which is using a Credential. This also includes a summary of the Connector it belongs to.
Show child attributes
Show child attributes
ID is the unique identifier of the Connection. Typically this is only used internally and most (if not all)
public-facing APIs will use the name in combination with the Connector's id instead.
Name is the name of the Connection.
ConnectorSummaryBase exposes a summary of a Connector irrespective of protocol.
Show child attributes
Show child attributes
ID is the unique identifier of the Connector.
OrganisationID is the unique identifier of the Organisation that owns the Connector.
Name is the user-provided name of the Connector
ProtocolType denotes the set of all valid connector types.
http, bigquery CreatedAt is the time at which the ConnectorVersion was created.
UpdatedAt is the time at which the ConnectorVersion was last updated, including any changes to child resources.
CreatedAt is the time the Connection was created.
UpdatedAt is the time the Connection was last updated.
Errors is a list of errors which occurred when attempting to validate the credential. This field may be undefined, which implies that validation has not occurred and the consumer cannot assume whether this Credential is valid or not. An empty array indicates that the Credential is valid.
ExpiresAt denotes the time this credential should be automatically deleted. External systems can subscribe to deletion events and if the reason is "expired", can trigger the correct notifications to interested parties (such as un-publishing jobs which rely on the credential and emailing the owner to rectify it).
Show child attributes
Show child attributes
AuthSchemeConfig defines how a Connector implements the AuthScheme in order to fulfil its authentication requirements. This is purely the configuration and not the actual credential which is used to authenticate. The credential uses this configuration to determine how to authenticate.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
"none"ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
CredentialBase is the base type for all credentials. It contains the common properties which are shared across all credential types.
Show child attributes
Show child attributes
ID is the unique identifier of the Credential.
OrganisationID is the unique identifier of the Organisation which owns the Credential.
CredentialType denotes the type of the credential which determines what the Credential's data property will
contain.
- none: No credential is required to authenticate with the Connector.
- string: The credential is a string value, such as an API key or password.
- binary: The credential is a binary value, such as a private key, certificate or other file.
- basic-auth: The credential is a username and password to be used for basic authentication.
- oauth2-client: The credential is an OAuth2 client ID and secret to be used for OAuth2 authentication.
- oauth2-code: The credential is a temporary authorization code which will be exchanged for an oauth2-token.
- oauth2-password: The credential is an OAuth2 username and password with an optional client ID and secret to be used for OAuth2 authentication.
- oauth2-token: The credential is an OAuth2 access_token to be used for OAuth2 authentication.
- custom-function: The credential is a custom function which will be called to authenticate with the Connector.
- jwt-bearer: The credential is the JWT setup values to be used for generating a bearer token.
- certificate: The credential is a PEM encoded certificate, key and CA to be used for TLS client authentication.
none, string, binary, basic-auth, oauth2-client, oauth2-code, oauth2-password, oauth2-token, custom-function, certificate, jwt-bearer Name is the name of the Credential.
CredentialDataNone contains no data as no credential is required to authenticate with the Connector. It is used purely as a placeholder to implement a consistent interface across all CredentialType/AuthSchemeTypes.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
CredentialUsages is a list of references to the Connectors which are using this Credential. To aid performance, this field will only be defined for specific endpoints. An undefined property means that the usages have not been loaded, whereas an empty array indicates that the credential is not used by any connectors.
Show child attributes
Show child attributes
CredentialUsageConnection contains the information about an Connection which is using a Credential. This also includes a summary of the Connector it belongs to.
Show child attributes
Show child attributes
ID is the unique identifier of the Connection. Typically this is only used internally and most (if not all)
public-facing APIs will use the name in combination with the Connector's id instead.
Name is the name of the Connection.
ConnectorSummaryBase exposes a summary of a Connector irrespective of protocol.
Show child attributes
Show child attributes
ID is the unique identifier of the Connector.
OrganisationID is the unique identifier of the Organisation that owns the Connector.
Name is the user-provided name of the Connector
ProtocolType denotes the set of all valid connector types.
http, bigquery CreatedAt is the time at which the ConnectorVersion was created.
UpdatedAt is the time at which the ConnectorVersion was last updated, including any changes to child resources.
CreatedAt is the time the Connection was created.
UpdatedAt is the time the Connection was last updated.
Errors is a list of errors which occurred when attempting to validate the credential. This field may be undefined, which implies that validation has not occurred and the consumer cannot assume whether this Credential is valid or not. An empty array indicates that the Credential is valid.
ExpiresAt denotes the time this credential should be automatically deleted. External systems can subscribe to deletion events and if the reason is "expired", can trigger the correct notifications to interested parties (such as un-publishing jobs which rely on the credential and emailing the owner to rectify it).
CreatedAt is the time the Connection was created.
UpdatedAt is the time the Connection was last updated.
CreatedAt is the time the user was created.
UpdatedAt is the time the user was last updated.
EndUserIntegration represents an integration that is available to an end user.
This object is only a summary of the integration and does not contain all the information to enable the user to activate it. The GetEmbeddedIntegration endpoint should be used to retrieve the full integration details.
Show child attributes
Show child attributes
Name is a short name for the integration, this is typically the name of the Connector being integrated to.
ImageURL is a URL to an image/icon that represents the integration. This image is used within the integration tile displayed in the embedded UI.
Description can be used to provide a longer description of the integration. This can be shown to end users in the embedded integration hub UI.
IsDeployed indicates whether the integration is deployed and available to end users. If not deployed, the integration cannot be activated.
IsActivated indicates whether the integration is activated for the end user. If the integration is not activated, the user can activate it from the embedded integration hub.
VariablesSchema is the JSON schema for the variables defined for this integration.