Upsert Auth Scheme Config to Connector

PUT

{organisation_id}

connectors

{connector_id}

auth-scheme-configs

{auth_scheme_config_id}

curl --request PUT \
  --url https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/auth-scheme-configs/{auth_scheme_config_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "<string>",
  "description": "<string>",
  "validationMessages": [
    {
      "text": "<string>",
      "severity": "info",
      "detail": [
        "<string>"
      ]
    }
  ],
  "schemeType": "<string>"
}'

{
  "id": "<string>",
  "organisationId": "<string>",
  "name": "<string>",
  "public": true,
  "documentationURL": "<string>",
  "imageURL": "<string>",
  "tags": {},
  "protocol": "http",
  "authSchemeConfigs": [
    {
      "id": "<string>",
      "description": "<string>",
      "validationMessages": [
        {
          "text": "<string>",
          "severity": "info",
          "detail": [
            "<string>"
          ]
        }
      ],
      "schemeType": "<string>"
    }
  ],
  "connectionVariables": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "connections": [
    {
      "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"
    }
  ],
  "versions": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "isLatest": true,
      "isDefault": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "publishedAt": "2023-11-07T05:31:56Z",
      "messages": [
        {
          "text": "<string>",
          "severity": "info",
          "detail": [
            "<string>"
          ]
        }
      ]
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "baseUrl": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer token authentication used by the Versori Platform. External consumers must provide an API key, however internal consumers must provide a JWT id_token issued by our IdP.

Path Parameters

organisation_id

string

required

connector_id

string

required

ID is the unique identifier of the Connector.

auth_scheme_config_id

string

required

Body

application/json

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.

string

required

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

string

required

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

schemeType

string

required

Allowed value: "none"

validationMessages

object[]

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.

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

string

required

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

string

required

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

schemeType

string

required

Allowed value: "none"

validationMessages

object[]

This field will be ignored if sent to the API.

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

string

required

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

string

required

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

schemeType

string

required

Allowed value: "api-key"

name

string

required

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

enum<string>

required

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

Available options:

query,

header,

cookie

validationMessages

object[]

This field will be ignored if sent to the API.

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

string

required

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

string

required

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

schemeType

string

required

Allowed value: "basic-auth"

validationMessages

object[]

This field will be ignored if sent to the API.

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

string

required

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

string

required

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

schemeType

string

required

Allowed value: "oauth2"

authorizeUrl

string

required

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

tokenUrl

string

required

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

scopes

object[]

required

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.

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

defaultScopes

string[]

required

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.

grant

object

required

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.

validationMessages

object[]

This field will be ignored if sent to the API.

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

additionalAuthorizeParams

string

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

string

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.

mtlsEnabled

boolean

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.

mtlsCredentialId

string

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.

string

required

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

string

required

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

schemeType

string

required

Allowed value: "hmac"

name

string

required

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

enum<string>

required

AuthSchemeConfigHMACIn defines where the signature should be set on requests.

Available options:

query,

header,

cookie

algorithm

enum<string>

required

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

Available options:

sha1,

sha256,

sha512

digestInputs

enum<string>[]

required

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.

Available options:

body,

url

validationMessages

object[]

This field will be ignored if sent to the API.

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

string

required

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

string

required

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

schemeType

string

required

Allowed value: "certificate"

validationMessages

object[]

This field will be ignored if sent to the API.

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

Response

200

application/json

Connector represents a connector to an external system.

string

required

ID is the unique identifier of the Connector.

organisationId

string

required

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

name

string

required

Name is the user-provided name of the Connector

public

boolean

required

protocol

enum<string>

required

ProtocolType denotes the set of all valid connector types.

Available options:

http,

bigquery

authSchemeConfigs

object[]

required

connections

object[]

required

Connections is a list of all the connections this Connector has.

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.

connections.id

string

required

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.

connections.name

string

required

Name is the name of the Connection. This must be unique within the owning Connector.

connections.credentials

object

required

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.

connections.credentials.action

object[]

ConnectionCredential contains the a Credential and the AuthSchemeConfig to define how the Credential should be used against the Connection's Connector.

connections.credentials.action.id

string

required

connections.credentials.action.authSchemeConfig

object

required

connections.credentials.action.credential

object

required

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

connections.credentials.action.credential.id

string

required

ID is the unique identifier of the Credential.

connections.credentials.action.credential.organisationId

string

required

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

connections.credentials.action.credential.type

enum<string>

required

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.

Available options:

none,

string,

binary,

basic-auth,

oauth2-client,

oauth2-code,

oauth2-password,

oauth2-token,

custom-function,

certificate,

jwt-bearer

connections.credentials.action.credential.name

string

required

Name is the name of the Credential.

connections.credentials.action.credential.data

object

required

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.

connections.credentials.action.credential.usages

object[]

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.

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.

connections.credentials.action.credential.errors

string[]

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.

connections.credentials.action.credential.expiresAt

string

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

connections.credentials.trigger

object[]

ConnectionCredential contains the a Credential and the AuthSchemeConfig to define how the Credential should be used against the Connection's Connector.

connections.credentials.trigger.id

string

required

connections.credentials.trigger.authSchemeConfig

object

required

connections.credentials.trigger.credential

object

required

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

connections.credentials.trigger.credential.id

string

required

ID is the unique identifier of the Credential.

connections.credentials.trigger.credential.organisationId

string

required

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

connections.credentials.trigger.credential.type

enum<string>

required

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.

Available options:

none,

string,

binary,

basic-auth,

oauth2-client,

oauth2-code,

oauth2-password,

oauth2-token,

custom-function,

certificate,

jwt-bearer

connections.credentials.trigger.credential.name

string

required

Name is the name of the Credential.

connections.credentials.trigger.credential.data

object

required

connections.credentials.trigger.credential.usages

object[]

connections.credentials.trigger.credential.errors

string[]

connections.credentials.trigger.credential.expiresAt

string

connections.variables

object[]

required

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

connections.createdAt

string

required

CreatedAt is the time the Connection was created.

connections.updatedAt

string

required

UpdatedAt is the time the Connection was last updated.

versions

object[]

required

Versions is a list of all the versions this Connector has.

ConnectorVersion represents a version of a Connector.

createdAt

string

required

CreatedAt is the time at which the ConnectorVersion was created.

updatedAt

string

required

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

baseUrl

string

required

BaseURL is the base URL of all HTTP Actions within the Connector.

documentationURL

string

Hold an optional link to the documentation for the API.

imageURL

string

The URL for the icon for the connector

API Reference

Connect API

Embedded API

Organisations API

Proxy API

Authorizations

Path Parameters

Body

Response