API Reference
Connect API
- Introduction
- Endpoints
Embedded API
- Introduction
- Endpoints
- Hubs
- End Users
- Connections
- Integrations
- Connectors
- Embed
- Activations
- Miscellaneous
Organisations API
- Overview
- Signing Keys
Create End User Connection
CreateEndUserConnection creates a new Connection for the given User. The Connection is used to authenticate the user to a Hub Connector.
This endpoint is typically only used for more bespoke implementations where an End User needs to authenticate to a Connector outside of the normal activation flow, for example where credentials are provided by another API and not through End User actions in the embedded UI.
curl --request POST \
--url https://platform.versori.com/api/embedded/v1/hubs/{hub_id}/users/{user_id}/connections \
--header 'Content-Type: application/json' \
--data '{
"connectorId": "<string>",
"connection": {
"name": "<string>",
"credentials": {
"action": [
{
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"schemeType": "<string>"
},
"credential": {
"name": "<string>",
"type": "none",
"data": {}
}
}
],
"trigger": [
{
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"schemeType": "<string>"
},
"credential": {
"name": "<string>",
"type": "none",
"data": {}
}
}
]
},
"variables": [
{
"name": "<string>",
"value": "<string>"
}
]
}
}'{
"id": "<string>",
"name": "<string>",
"credentials": {
"action": [
{
"id": "<string>",
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"schemeType": "<string>"
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"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>"
],
"data": {},
"expiresAt": "2023-11-07T05:31:56Z"
}
}
],
"trigger": [
{
"id": "<string>",
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"schemeType": "<string>"
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"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>"
],
"data": {},
"expiresAt": "2023-11-07T05:31:56Z"
}
}
]
},
"variables": [
{
"name": "<string>",
"value": "<string>"
}
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}Path Parameters
UserID references an End User in the Hub.
Most APIs support setting this value to either the internal Versori identifier or their external ID as
determined by the organisation. The identifier_type query parameter is used to indicate which type of ID is
being used.
Query Parameters
IdentifierType indicates whether the user_id path parameter is a internal identifier created by Versori, or an
external identifier. If the value is external, some endpoints also require the hub query parameter to
identify the correct Hub.
internal, external Body
ConnectionCreate defines the connection to create against a Connector.
Name is the name of the Connection.
ConnectionCredentialsCreate defines the Action and Trigger credentials for the owning Connector.
This supports defining multiple credentials for each type, which 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.
This object can either define a reference to an existing Credential via the InferredReference object, or it can define a new Credential via the CredentialCreate object.
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.
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.
CredentialCreateBase contains the common fields to create a new credential.
Name is the name of 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 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.
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.
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.
CredentialCreateBase contains the common fields to create a new credential.
Name is the name of 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 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.
Response
Connection defines the Action and Trigger credentials for the owning Connector, and additional variables which can be used to customize the Connector in a particular connection.
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.
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.
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.
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.
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.
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.
CredentialUsageConnection contains the information about an Connection which is using a Credential. This also includes a summary of the Connector it belongs to.
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).
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.
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.
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.
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.
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.
CredentialUsageConnection contains the information about an Connection which is using a Credential. This also includes a summary of the Connector it belongs to.
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.
curl --request POST \
--url https://platform.versori.com/api/embedded/v1/hubs/{hub_id}/users/{user_id}/connections \
--header 'Content-Type: application/json' \
--data '{
"connectorId": "<string>",
"connection": {
"name": "<string>",
"credentials": {
"action": [
{
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"schemeType": "<string>"
},
"credential": {
"name": "<string>",
"type": "none",
"data": {}
}
}
],
"trigger": [
{
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"schemeType": "<string>"
},
"credential": {
"name": "<string>",
"type": "none",
"data": {}
}
}
]
},
"variables": [
{
"name": "<string>",
"value": "<string>"
}
]
}
}'{
"id": "<string>",
"name": "<string>",
"credentials": {
"action": [
{
"id": "<string>",
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"schemeType": "<string>"
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"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>"
],
"data": {},
"expiresAt": "2023-11-07T05:31:56Z"
}
}
],
"trigger": [
{
"id": "<string>",
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"schemeType": "<string>"
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"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>"
],
"data": {},
"expiresAt": "2023-11-07T05:31:56Z"
}
}
]
},
"variables": [
{
"name": "<string>",
"value": "<string>"
}
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}