API Reference

Authorization

Versori User Documentation

Home

Integrate

Embedded

GetActivation returns the Activation for the given ID.


Retrieve an Activation

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.


Name is the query parameter/header/cookie name which will be used to send the API key.

AuthSchemeConfigAPIKey defines how a Connector uses an API key credential to authenticate with the system.


AuthSchemeConfigAPIKeyIn defines the location of the API key in the request.


Description enables users to distinguish multiple configurations which use the same 
schemeType.


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.


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.


AuthSchemeConfigBasicAuth is a placeholder object with the schemeType set to `basic-auth`. There is no other
configuration required.


AuthSchemeConfigCertificate is a placeholder object with the schemeType set to `certificate`. 
There is no other config required


AuthSchemeConfigHMACAlgorithm defines the hashing algorithm to use when generating the HMAC signature.

AuthSchemeConfigHMACInputs defines what parts of a HTTP request are consumed to generate the HMAC signature. Some systems
only generate the signature from the request body, others may include the URL. The order of this array
defines the order in which the input is fed into the hashing function.


Name is the query parameter/header/cookie name which will be used to send the signature.

AuthSchemeConfigHMAC defines how a Connector uses an HMAC credential to authenticate with the system.

This may be used on outbound requests to sign the request body, however it is more commonly used on inbound
requests (i.e. from Webhook Triggers) to verify the sender of the request is allowed to invoke the Trigger.


AuthSchemeConfigHMACIn defines where the signature should be set on requests.

AuthSchemeConfigNone is a placeholder object with the schemeType set to `none`. There is no other configuration
required.


AdditionalAuthorizeParams is a URL-encoded query string which should be attached to 
the AuthorizeURL when the user is redirected to the OAuth 2.0 authorization 
endpoint.

This value is only used by the UI to drive the default values when connecting, the 
API to `InitialiseOAuth2Connection` can be provided a different value if required.


AdditionalTokenParams is a URL-encoded string following the 
`application/x-www-form-urlencoded` mime-type, which can be used to pass additional
parameters to the OAuth 2.0 token endpoint within the request body.


AuthorizeURL is the URL which the user will be redirected to in order to authorize 
the application.


DefaultScopes is the list of scopes which will be requested by default when the user
connects the Connector. This is useful for Connectors which require a specific set 
of scopes to function correctly.


MTLSCredentialID is the unique identifier of the Credential which contains the 
client certificate and private key to be used as part of the mTLS connection. 

This may be unset when creating a connection, in which case if `mtlsEnabled` is 
true, then the API will find an associated AuthSchemeConfigCertificate and link 
them automatically.


MTLSEnabled is a flag which determines whether the Connector should use Mutual TLS 
(mTLS) to authenticate with the OAuth 2.0 token endpoint. This is useful for 
Connectors which require a higher level of security.


Scopes is the list of all OAuth2 scopes which the application supports. The user 
will be allowed to choose which scopes to request when configuring the Connection.


TokenURL is the URL which the application will use to issue an access token.


AuthSchemeConfigOAuth2 defines how a Connector uses an OAuth2 credential to authenticate 
with the system. This is to be used for all OAuth 2.0 flows which require a client ID and 
client secret as part of the Connector's configuration. Connectors which use the 
`client_credentials` grant type, where the user provides the Client ID  and Client Secret at
the point where they connect, should use the `AuthSchemeConfigOAuth2ClientCredentials` type 
instead.


AuthSchemeConfigOAuth2GrantAuthorizationCode contains grant-specific configuration for the 
`authorization_code` grant type.

How the API manages changes to this configuration is as follows:

- CredentialID and OrganisationID are not set, a new credential is created containing the
  sensitive information and the non-sensitive information is updated in the database.  
- Otherwise, both the credential and the database are updated using JSON Merge Patch, with
  undefined properties not being updated.
- Any other permutation will result in a 400 Bad Request.


ClientID is the OAuth 2.0 client's identifier. This is not a sensitive value and may be 
presented to the user in plaintext.


ClientSecret is the OAuth 2.0 client's secret. This is a sensitive value and will not be
displayed to the user.


CredentialID is the unique identifier of the Credential which contains the client ID and
client secret to be used as part of the `password` flow.


OrganisationID is the unique identifier of the Organisation that owns the Credential. 
This can be different to the Connector's OrganisationID since some may be imported from 
Versori's public library.


AuthSchemeConfigOAuth2GrantPassword contains grant-specific configuration for the `password` 
grant type.

How the API manages changes to this configuration is as follows:

- CredentialID and OrganisationID are not set, a new credential is created containing the
  sensitive information and the non-sensitive information is created/updated in the 
  database.  
- Otherwise, both the credential and the database are updated using JSON Merge Patch.
- Any other permutation will result in a 400 Bad Request.


ClientID is the OAuth 2.0 client's identifier. This is not a sensitive value and may be presented to the 
user in plaintext.


ClientSecret is the OAuth 2.0 client's secret. This is a sensitive value and will not be displayed to the 
user. It may be populated when updating the Credential.


OrganisationID is the unique identifier of the Organisation that owns the Credential. This can be different
to the Connector's OrganisationID since some may be imported from Versori's public library.


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.


CreatedAt is the time the Connection was created.

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.

UpdatedAt is the time the Connection was last updated.

ConnectionCredential contains the a Credential and the AuthSchemeConfig to define how the Credential should be used against the Connection's 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.


ConnectionVariable denotes an arbitrary key/value pair which can be used to configure a connector.

Name is the name of the connection variable.

Value is the value of the connection variable.

ConnectorSummaryBase exposes a summary of a Connector irrespective of protocol.

CreatedAt is the time at which the ConnectorVersion was created.

ID is the unique identifier of the Connector.

Name is the user-provided name of the Connector

OrganisationID is the unique identifier of the Organisation that owns the Connector.

UpdatedAt is the time at which the ConnectorVersion was last updated, including any changes to child
resources.


CredentialBase is the base type for all credentials. It contains the common properties which are shared across
all credential types.


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).


ID is the unique identifier of the Credential.

OrganisationID is the unique identifier of the Organisation which owns the Credential.

CredentialDataBasicAuth contains the username and password required to authenticate with the Connector. The
`password` property will be redacted when returned in a response.


Password is the password used to authenticate with the Connector. Will be redacted when returned in a
response.


Username is the username used to authenticate with the Connector.

CredentialDataBinary is commonly used to store non-string data such as binary files or encryption keys. This 
value will be redacted when returned in a response.


Value is a base64 encoded string containing the credential data. This could decode to a valid utf-8 string,
or it could decode to a binary file such as a private key etc. When read from the API this field will be 
redacted.


CredentialDataCertificate contains the Certificate, Certificate key and CA(Certificate authority).


CA is the Certificate Authority to verify the server certificates against.

Certificate is the certificate that will be send to the connection.

Key is the accompanying key for the certificate.

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.


CredentialDataOAuth2Client contains the OAuth2 client credentials required to either issue an access token from
a refresh_token, or via the `client_credentials` and `authorization_code` grant types. The `clientSecret` property will be redacted when
returned in a response.


AdditionalParams is a URL-encoded query string which can be used to pass additional 
parameters to the OAuth 2.0 token endpoint. These parameters are attached to the body
in the formatted as the `application/x-www-form-urlencoded` content-type.


AuthorizeURL is the URL which the user will be redirected to in order to authorize the application. If
the client is being used for a `client_credentials` grant type, this field should be set to an empty 
string.


ClientID is the OAuth2 client ID used to authenticate with the Connector.


ClientSecret is the OAuth2 client secret used to authenticate with the Connector. Will be redacted when
returned in a response.


MTLSCredentialID is an optional reference to another credential being created. 
If set the certificate credential will be used when making a request to the tokenUrl.


MTLSEnabled is a boolean flag which determines whether the client should use mutual TLS authentication when 
communicating with the OAuth2 provider. If enabled, the `mTLSCredentialId` field must be set, or it must be 
created via the `CreateConnection` endpoint with an associated mTLS credential defined beforehand, in which
case the mTLSCredentialID field will be populated upon saving by the API.


Scopes is a list of scopes which should be requested when issuing an access token. This is only required if
this credential is being used on a `client_credentials` grant type, for `authorization_code` grant types the
requested scopes come from the `CredentialDataOAuth2Token` credential.


TokenURL is the URL which the application will use to issue an access token.

CredentialDataOAuth2Code is used to exchange an authorization code for an access token and
is denoted by the `oauth2-code` type. 
This is only used when creating or updating an OAuth 2.0 connection using the 
`authorization_code` grant type. Retrieving this credential will return a payload of
type `oauth2-token` in the shape of a `CredentialDataOAuth2Token` object.


Code is the authorization code which will be exchanged for an access token.


State is the state value which is propagated through the OAuth2 flow.


CredentialDataOAuth2Password contains the username and password of a Resource Owner within an OAuth 2.0
application. The `password` property will be redacted when returned in a response.


CredentialDataOAuth2Token is primarily used to store the refresh_token for an user who has authorized an OAuth2
Application to access their data. However, this information is not exposed publicly and the only data visible
via the API are the `scopes` which the user has granted consent for. This can be used to determine whether
the user should be prompted to re-authorize the application with additional scopes in the event they choose to
use a new endpoint which requires additional scopes to what they've already consented to.


AccessToken is the OAuth2 access token which can be used to authenticate with the Connector. This 
information is redacted when read from the API.


ExpiresAt is the time at which the access token will expire. If not defined, the accessToken will be 
reused until a 401 response is received from the Connector, at which point the token should be refreshed
with the provided `refreshToken`. Ideally this should be provided so that erroneous failures can be 
avoided.


RefreshToken is the OAuth2 refresh token which can be used to issue new access tokens. This information is
redacted when read from the API.

This is a required field as it is used to refresh the access token when it expires. If users are providing
an access token which does not expire using this credential type, then the same functionality may be 
achieved by using a simple API key and OAuth 2.0 need not be used.


Scopes is a list of scopes which the user has granted consent for.

TokenType is the type of token which is being issued. Defaults to "Bearer" if not set.


CredentialDataString contains a string value and nothing else and is commonly used for API keys. This value 
will be redacted when returned in a response.


Value is a UTF-8 string containing the credential data. When read from the API this field will be redacted.


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.


CredentialUsage contains the information about a Connector which is using a Credential. This object currently
only supports tracking usage by other connections, but in the future new fields may be added to track usage
by other entities such as, but not limited to, Boards, Hubs and Users.


CredentialUsageConnection contains the information about an Connection which is using a Credential. This also
includes a summary of the Connector it belongs to.


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.


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.


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.


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.


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.


IsDeployed indicates whether the integration is deployed and available to end users. If not deployed, the
integration cannot be activated.


Name is a short name for the integration, this is typically the name of the Connector being integrated to.


VariablesSchema is the JSON schema for the variables defined for this integration.


CreatedAt is the time the user was created.

DisplayName is an optional human-readable name for the user. If not set, the default is an empty string.


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.


ID is the Versori identifier for the user. Most APIs will not use this field but instead reference
users by their externalId.


PrimaryConnection is the connection that the user will use to authenticate to the primary connector.


UpdatedAt is the time the user was last updated.

ErrorField denotes a field which has an error.

Field is the name of the field which has an error, this may be a path to a nested field, including array
elements. The format of this field is of the form: "field1.field2[0].field3"


Message is the error message for this specific field.

Message is a message to be displayed to the user to indicate some information about the
preceding request.


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.


OAuth2Scope represents a single scope which can be requested by an OAuth2 application.


Description describes the scope in human-friendly terminology. This text may be 
displayed to users via a help tooltip or similar.


Name is the name of the scope as determined by the application to which this Connector 
is connecting to.


ProtocolType denotes the set of all valid connector types.

Welcome to the Versori Platform documentation.

Welcome

Introduction

Connect your APIs to the Versori Platform.

Overview

Learn about the protocols used by the Versori Platform.

Protocols

Authentication Methods

Actions

Triggers

Provide credentials for a Connector to facilitate Versori to interact with an external system.

Connections

Build integrations between your systems with Boards.

How It Works

Creating a Hub

Quickstart React

Quickstart

React SDK

Build integrations between your internal systems.

Boards are the entrypoint to building integrations.

Select one of the following APIs to get started

Learn how to authenticate with the Versori Platform.

Authentication

Our next-generation API for connecting to your external systems.

Our next-generation API for exposing Versori-powered integrations to your users.

Organisations API provides access to manage your Versori Organisation.

CreateSigningKey creates a new Signing Key for the Organisation. 

This API creates a new RSA key pair, storing the public key and returning the private key. The private key must 
be kept secure and should not be shared publicly as it has the ability to sign JWTs which can be used to 
authenticate to Versori APIs on behalf of your Organisation (or scoped to a specific End User within 
Versori Embedded).

If the private key is lost, it cannot be recovered and a new key pair must be generated. In this scenario, it is
the Organisation's responsibility to delete the Signing Key from Versori so that any JWTs signed by the lost key
are invalidated.


Create Signing Key

ListSigningKeys returns a list of all Signing Keys for the Organisation.


List Signing Keys

DeleteSigningKey deletes the signing key for the Organisation.

Any existing JWTs signed by this key will be invalidated and will no longer be accepted by the Versori platform.


Delete Signing Key

GetPublicKey returns the public key for the given Signing Key ID. This can be used to verify JWTs signed by an 
Organisation's Signing Key.


Retrieve public key

Proxy API enables authenticated requests through Connections in the Platform.

Use Cases

Endpoint

Welcome to the user documentation for the Versori Platform

Core Concepts

Within Switchboard, apps are the external-system nodes that you use to build out your integrations.

Apps

Boards

The Board Editor is your main tool for creating and editing boards. It is a visual tool that allows you to create and edit boards by dragging and dropping components onto the board.

Board Editor

The Hubs SDK is a tool that allows the users of your Product to integrate into different Apps you have configured in the Versori Platform.

Hubs SDK

Learn how to use Actions to automate your workflows.

The transformer action is a drag and drop action that allows you to transform the data in your workflow.

Transformer

The Databuilder allows for familiar form based templating and transformations

Databuilder

The filter action allows you to filter the resulting data based on a series of conditions.

Filter

Datamapper provides storage within Switchboard for remembering cross-system references to different entities.

Datamapper

The Batch action allows you to aggregate requests into a single output format.

Batch

The Delay Action is used to delay the execution of the next node in the workflow.

Delay

The Splitter Action accepts a List input and splits each item to be processed individually.

Splitter

The Trigger Action is used as a startpoint within your flows, to trigger requests either manually or on a schedule.

Trigger

Boards are built from Apps, and Actions in a drag-and-drop interface.

How to create a Board, an use the Board Editor

Multiple methods of connecting your apps are available.

How to Connect to your Apps

When building your integrations - you can add your operations from different systems, and provide further configuration.

How to add a Webhook Listener into your Integration

Selectors provide an intuitive interface for plucking data from previous steps in your flow, to be used within your requests and actions.

How to use Selectors to template data within your Integrations

The Hubs SDK enables users to authenticate and onboard into external integrations that are connected to your product

How to use the Versori Hubs SDK

Preview the output of a transformer. This endpoint is useful for testing a transformer before creating an integration.


Preview the output of a transformer.

Retrieve a signed URL for uploading a schema specification


Upload a schema document based on a source URL. The server will download this URL and upload to object
storage automatically.


SchemaInfo processes the schema referenced by the provided URL and returns information to allow a user to create
an App.

Deprecated: This endpoint is no longer supported, users should create a Schema using the `CreateSchema`
(POST /organisations/{organisationId}/schemas) operation, and use the `GetSchemaInfo` operation to retrieve
this information.


Retrieve a signed URL for uploading assets


API Reference

Connect API

Embedded API

Organisations API

Proxy API

Retrieve an Activation

Path Parameters

Response