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 an End User
CreateEndUser creates a new End User for the given Hub.
The end user requires a unique externalId which is recommended to be the same as the user’s ID on the
Primary Connector for the Hub. This is an immutable field so should not be set to something that may change
such as an email address.
Before an end user can activate an Integration, they must also have a Connection defined for the Primary Connector. This may be created as part of this request, a separate request to CreateConnection, or as part of the request in the first Activate call.
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Request to create a new End User
ExternalID is the identifier of the user as identified in the Hub's primary connector/system.
DisplayName is a human-readable name for the user
PrimaryConnection is the connection that the user will use to authenticate to the primary 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.
Path Parameters
Body
Request to create a new End User
ExternalID is the identifier of the user as identified in the Hub's primary connector/system.
PrimaryConnection is the connection that the user will use to authenticate to the primary 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.
DisplayName is a human-readable name for the user
Response
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.
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.
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.
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.
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.
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.