curl --request POST \
--url https://platform.versori.com/api/embedded/v1/hubs/{hub_id}/users/{user_id}/connections \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"connectorId": "<string>",
"connection": {
"name": "<string>",
"credentials": {
"action": [
{
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"schemeType": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"credential": {
"name": "<string>",
"type": "none",
"data": {}
}
}
],
"trigger": [
{
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"schemeType": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<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>",
"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"
}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 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"connectorId": "<string>",
"connection": {
"name": "<string>",
"credentials": {
"action": [
{
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"schemeType": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"credential": {
"name": "<string>",
"type": "none",
"data": {}
}
}
],
"trigger": [
{
"authSchemeConfig": {
"id": "<string>",
"description": "<string>",
"schemeType": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<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>",
"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"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
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.
Show child attributes
Show child attributes
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.
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.
CredentialCreateBase contains the common fields to create a new credential.
Show child attributes
Show child attributes
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.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
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.
CredentialCreateBase contains the common fields to create a new credential.
Show child attributes
Show child attributes
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.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
Response
Created
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.
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.