> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versori.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create HTTP Connector
> CreateHTTPConnector creates a new HTTP Connector. By default the Connector will be created in a draft state and
will need to be published before it can be used by other Versori products.
## OpenAPI
````yaml post /o/{organisation_id}/protocols/http/connectors
openapi: 3.1.0
info:
title: Versori Connect API
version: 0.0.1
license:
name: UNLICENSED
identifier: UNLICENSED
description: >
Connect API allows you to connect to your external systems to the Versori
Platform.
The main component of the Connect API are Connectors. Connectors are split
into the following components:
- Protocol
- Authentication Scheme
- Connections
- Global Parameters
- Actions
- Triggers
- Definitions
## Protocol
The protocol defines the transport mechanism used to communicate with your
external system.
Currently, only HTTP/REST APIs are supported within Connect API, however our legacy "Apps" functionality is
available on [Switchboard API](/api-reference/switchboard-api) which supports GraphQL APIs and SOAP web
services.
## Authentication Scheme
The authentication scheme defines how the Versori Platform will authenticate
with your external system. Different
schemes are applicable to different protocols.
### HTTP
The following authentication schemes are supported for HTTP:
- OAuth 2.0 - OIDC - API Key (in header, query or cookie) - Basic - Bearer
## Connections
Each Connector has at least one connection and additional connections can be
added. Connections are used to connect
to different instances of your external system. For example, you may have a
development, staging and production
connection, each with different credentials and addresses. Each Connection
must provide a Credential which satisfies
one authentication scheme for the Connector. Connections can define
variables, which can be used to customise
certain aspects of the Connector such as default values for certain
fields/parameters.
Finally, some protocols may require specific configuration for each
connection. For example, the HTTP Protocol
requires a base URL for each connection.
## Global Parameters
Global Parameters allows a user to configure a set of parameters which can
be used across multiple Actions. Within
the UI, whenever a user starts to create a new Action the UI will
pre-populate the Action with the Global
Parameters. If the Action in question does not require any of these
parameters the user may delete them before
saving.
When a user creates, updates or deletes a global parameter, the user will be
prompted to choose which Actions should
reflect the change, with the ability to choose all, some or none.
### HTTP Parameters
For HTTP Connectors, the following parameter types may be set as Global
Parameters: - Path parameters - Query
parameters - Headers
## Actions
Actions define the actions that can be performed on your external system. An
action may be defined and implemented
differently depending on the protocol. For example, an HTTP Action contains
a method like GET, PUT, POST etc.,
whereas a BigQuery Actions will contain a SQL query.
### HTTP
For HTTP Connectors, each Action defines a single HTTP request.
The Action can contain inputs to customise the request, some inputs may also
allow default values which can be
overridden when used within other Versori products. Default values can be
defined using connection variables.
The supported HTTP inputs are: - Path parameters - Query parameters -
Headers - Request body Definitions (one per
supported media-type)
The Action can also define outputs: - Headers - Status Codes, and their
associated Response body Definitions (one
per supported media-type)
### BigQuery SQL
BigQuery SQL Actions are defined as SQL queries. The query can contain
parameters to customise the query at runtime,
for example in Switchboard a user may use literal values or Selectors to
provide the parameters. This functionality
is provided via the
[query](https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query)
API endpoint.
When creating a BigQuery SQL Action, the associated Definition is
automatically created based on the query.
## Triggers
Triggers define how the Versori Platform will be notified of events from
your external system. Each Protocol
determines how Triggers are defined since how they are implemented may vary.
### HTTP Triggers
These are essentially webhooks, which an external service may invoke to
notify the Versori Platform of an event.
They are modelled similarly to HTTP Actions, but Versori expects a certain
request and allows the user to configure
the response.
In the future, you will also be able to define HTTP Trigger Lifecycles,
which define how a webhook is
created/deleted on the external system when a Switchboard integration is
published/unpublished. However, this is out
of scope for the initial release.
## Definitions
Definitions provide the Versori Platform the information required to
validate and provide auto-complete behaviour
when dealing with input/output data between connectors.
Each definition has a media-type and an associated schema. Which schema
implementation is used depends on the
media-type, we initially support the following: - `application/json`,
defined by JSON Schemas. - `text/xml`, defined
by XML Schema Definitions (XSDs). - `text/csv`, how this is defined isn't
known yet, however there are discussions
in JIRA about this.
## Versioning
Except for the top-level Connector data and their Connections, other aspects
of a Connector such as Actions,
Triggers and Definitions are versioned resources. A connector can have
multiple versions and each version can either
be in "draft" or "published" state. A version is published if its
`publishedAt` field is not null.
Versions are defined as an arbitrary string, but users are encouraged to
follow a consistent versioning scheme such
as SemVer, CalVer, or an incrementing number.
Connectors may only be used by Versori products if they are published, and
once published they are immutable. If an
edit is attempted against a published version then an error will be
returned. Unpublished Connectors are considered
to be in "draft" and can be edited as many times as required.
Connectors may be unpublished, but only when they are not referenced by any
other system (see
[Subscribers](#Subscribers) below).
### Special Versions
There are two reserved words to reference a published version, "latest" and
"default". "latest" will always return
the latest published version according to it's `publishedAt` field, whereas
"default" will return the version which
has been set as such by the user. If the user never specifies a default
version, the "latest" published version will
be used.
### Publishing Versions
When a new version is published, the user should be prompted to choose how
Versori products should handle the
update. For example, for Switchboard the user should be able to choose
whether to update existing integrations to
use the new version, or to leave them as they are. To facilitate this UX the
Connect API has the concept of
subscriptions (is there a better name?) where other APIs can register their
interest in a Connector.
## Subscribers
A Connector has the concept subscribers, where other products can notify the
Connect API of their interest in that
connector. This allows the Connect API to check whether a Connector is being
used by other products and prevent
deletion if so.
### Switchboard
When a board is published, the Switchboard orchestrator will subscribe to
the Connector. When that board is then
unpublished, the orchestrator will unsubscribe from the Connector.
## Completions
Coming Soon
Completions is an advanced feature of the Connect API which enables
Connector authors to define how a particular
field within a Definition may be auto-completed. This is useful for fields
which are almost always a fixed value but
whose valid values are determined by how the external system is configured.
i.e. the `channel` field in a Slack
`postMessage` call must be a valid channel name for the Slack Workspace in
which the Connector is connecting to.
There are different mechanisms for defining Completions which are described
below.
### Static Completions
Static Completions are defined by the Connector author and are a fixed list
of values. For JSON Definitions, this is
automatically generated by properties with the `enum` keyword. Other
media-types will have their own mechanisms
which may or may not be directly supported by their schema implementation.
### Remote Completions
Remote Completions make a connector to an external API to retrieve the valid
values for a field. Initially a
Completion can be defined by choosing another Connector Action, and a
transformation on how to extract the values to
present to the user.
servers:
- description: Production
url: https://platform.versori.com/api/connect/v1
- description: Staging
url: https://platform-staging.versori.com/api/connect/v1
- description: Development
url: http://localhost:8082
security:
- bearerToken: []
- cookie: []
tags:
- name: protocol-http
description: >
The HTTP Protocol allows the Connect API to communicate with external
systems via HTTP requests.
- name: connectors
description: >
Connectors are the core resource of the Connect API. They represent a
connector to an external system, and
contains the information required to interact with that system.
- name: connector-versions
description: >
Connector Versions belong to a Connector and maintains the set of Actions,
Triggers and Definitions for a
Connector.
- name: auth-schemes
description: >
Auth Schemes are the mechanism by which the Connect API authenticates with
external systems. They define how
Actions and Triggers are authenticated. Not all Auth Schemes are supported
by all Protocols, you can use the
[GET
/auth-schemes](/api-reference/connect-api/protocols/list-auth-schemes)
endpoint
to determine which Auth Schemes are supported for each Protocol.
- name: connections
description: |
Connections define how Actions and Triggers are authenticated.
- name: credentials
description: >
Credentials are the mechanism by which the Connect API authenticates with
external systems. They define how
Actions and Triggers are authenticated. Which Credentials are supported
depends on the Auth Scheme chosen, which
again is determined by the Protocol.
- name: actions
description: >
Actions define how the Versori Platform will interact with your external
system. Each Protocol determines how
Actions are defined since how they are implemented may vary.
- name: triggers
description: >
Triggers define how the Versori Platform may receive requests from your
external systems. Each Protocol
determines how Triggers are defined since how they are implemented may
vary.
- name: definitions
description: >
Definitions provide the Versori Platform the information required to
validate and provide auto-complete behaviour
when dealing with input/output data between connectors. Each definition
has a media-type and an associated schema
which is compatible with that media-type, for example JSON Schema is used
for `application/json` media-types.
- name: protocols
description: >
Protocols are the mechanism by which the Connect API communicates with
external systems. They define how Actions,
Triggers and Definitions are implemented.
- name: protocol-bigquery
description: >
The BigQuery Protocol allows the Connect API to communicate with BigQuery
datasets via the BigQuery API.
- name: misc
description: |
Miscellaneous endpoints which don't fit into any other category.
paths:
/o/{organisation_id}/protocols/http/connectors:
parameters:
- $ref: '#/components/parameters/organisation_id'
post:
tags:
- connectors
- protocol-http
summary: Create HTTP Connector
description: >
CreateHTTPConnector creates a new HTTP Connector. By default the
Connector will be created in a draft state and
will need to be published before it can be used by other Versori
products.
operationId: CreateHTTPConnector
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPConnectorCreate'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPConnector'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
organisation_id:
name: organisation_id
in: path
required: true
schema:
type: string
format: ulid
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
schemas:
HTTPConnectorCreate:
description: HTTPConnectorCreate is the input to the CreateHTTPConnector endpoint.
type: object
properties:
name:
type: string
description: Name is a user-friendly identifier for a Connector
baseUrl:
type: string
description: BaseURL is the base URL of all HTTP Actions within the Connector.
x-go-name: BaseURL
connectionVariables:
type: array
items:
$ref: '#/components/schemas/ConnectionVariable'
x-go-type-skip-optional-pointer: true
authSchemeConfigs:
type: array
items:
$ref: '#/components/schemas/AuthSchemeConfig'
tags:
$ref: '#/components/schemas/Tags'
public:
type: boolean
x-go-type-skip-optional-pointer: true
required:
- name
- baseUrl
- authSchemeConfigs
- connections
HTTPConnector:
description: HTTPConnector represents a connector to an external system over HTTP.
type: object
allOf:
- $ref: '#/components/schemas/ConnectorBase'
- properties:
protocol:
type: string
const: http
baseUrl:
type: string
description: >-
BaseURL is the base URL of all HTTP Actions within the
Connector.
x-go-name: BaseURL
public:
type: boolean
required:
- protocol
- public
- baseUrl
Error:
type: object
properties:
code:
type: string
description: Code is a machine-readable error code.
message:
type: string
description: Message is a human-readable error message.
fields:
type: array
items:
$ref: '#/components/schemas/ErrorField'
x-go-type-skip-optional-pointer: true
details:
type: string
x-go-type-skip-optional-pointer: true
required:
- code
- message
ConnectionVariable:
description: >-
ConnectionVariable denotes an arbitrary key/value pair which can be used
to configure a connector.
type: object
properties:
name:
type: string
description: Name is the name of the connection variable.
value:
type: string
description: Value is the value of the connection variable.
required:
- name
- value
AuthSchemeConfig:
description: >
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.
discriminator:
propertyName: schemeType
mapping:
none:
$ref: '#/components/schemas/AuthSchemeConfigNone'
api-key:
$ref: '#/components/schemas/AuthSchemeConfigAPIKey'
basic-auth:
$ref: '#/components/schemas/AuthSchemeConfigBasicAuth'
oauth2:
$ref: '#/components/schemas/AuthSchemeConfigOAuth2'
hmac:
$ref: '#/components/schemas/AuthSchemeConfigHMAC'
certificate:
$ref: '#/components/schemas/AuthSchemeConfigCertificate'
oneOf:
- $ref: '#/components/schemas/AuthSchemeConfigNone'
- $ref: '#/components/schemas/AuthSchemeConfigAPIKey'
- $ref: '#/components/schemas/AuthSchemeConfigBasicAuth'
- $ref: '#/components/schemas/AuthSchemeConfigOAuth2'
- $ref: '#/components/schemas/AuthSchemeConfigHMAC'
- $ref: '#/components/schemas/AuthSchemeConfigCertificate'
Tags:
type: object
x-go-type: map[string][]string
x-go-type-skip-optional-pointer: true
ConnectorBase:
description: >-
ConnectorBase holds common fields which exist across all Connector
protocols.
type: object
properties:
id:
type: string
format: ulid
description: ID is the unique identifier of the Connector.
x-go-name: ID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
organisationId:
type: string
format: ulid
description: >-
OrganisationID is the unique identifier of the Organisation that
owns the Connector.
x-go-name: OrganisationID
name:
type: string
description: Name is the user-provided name of the Connector
public:
type: boolean
documentationURL:
type: string
description: Hold an optional link to the documentation for the API.
x-go-type-skip-optional-pointer: true
imageURL:
type: string
description: The URL for the icon for the connector
x-go-type-skip-optional-pointer: true
tags:
$ref: '#/components/schemas/Tags'
protocol:
$ref: '#/components/schemas/ProtocolType'
authSchemeConfigs:
type: array
items:
$ref: '#/components/schemas/AuthSchemeConfig'
connectionVariables:
type: array
description: >-
Connection Variables is a list of default variables initialised in
every connector connection.
items:
$ref: '#/components/schemas/ConnectionVariable'
x-go-type-skip-optional-pointer: true
connections:
type: array
description: Connections is a list of all the connections this Connector has.
items:
$ref: '#/components/schemas/Connection'
versions:
type: array
description: Versions is a list of all the versions this Connector has.
items:
$ref: '#/components/schemas/ConnectorVersion'
x-go-type-skip-optional-pointer: true
createdAt:
type: string
format: date-time
description: CreatedAt is the time at which the ConnectorVersion was created.
updatedAt:
type: string
format: date-time
description: >
UpdatedAt is the time at which the ConnectorVersion was last
updated, including any changes to child
resources.
required:
- id
- organisationId
- name
- public
- protocol
- authSchemeConfigs
- connections
- versions
- createdAt
- updatedAt
ErrorField:
description: ErrorField denotes a field which has an error.
type: object
properties:
field:
type: string
description: >
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:
type: string
description: Message is the error message for this specific field.
required:
- field
- message
AuthSchemeConfigNone:
description: >
AuthSchemeConfigNone is a placeholder object with the schemeType set to
`none`. There is no other configuration
required.
type: object
allOf:
- $ref: '#/components/schemas/AuthSchemeConfigBase'
- type: object
properties:
schemeType:
type: string
const: none
required:
- schemeType
AuthSchemeConfigAPIKey:
description: >
AuthSchemeConfigAPIKey defines how a Connector uses an API key
credential to authenticate with the system.
type: object
allOf:
- $ref: '#/components/schemas/AuthSchemeConfigBase'
- type: object
properties:
schemeType:
type: string
const: api-key
name:
type: string
description: >-
Name is the query parameter/header/cookie name which will be
used to send the API key.
in:
$ref: '#/components/schemas/AuthSchemeConfigAPIKeyIn'
required:
- schemeType
- name
- in
AuthSchemeConfigBasicAuth:
description: >
AuthSchemeConfigBasicAuth is a placeholder object with the schemeType
set to `basic-auth`. There is no other
configuration required.
type: object
allOf:
- $ref: '#/components/schemas/AuthSchemeConfigBase'
- type: object
properties:
schemeType:
type: string
const: basic-auth
required:
- schemeType
AuthSchemeConfigOAuth2:
description: >
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.
type: object
allOf:
- $ref: '#/components/schemas/AuthSchemeConfigBase'
- type: object
properties:
schemeType:
type: string
const: oauth2
authorizeUrl:
type: string
format: uri
description: >
AuthorizeURL is the URL which the user will be redirected to in
order to authorize
the application.
x-go-name: AuthorizeURL
tokenUrl:
type: string
format: uri
description: >
TokenURL is the URL which the application will use to issue an
access token.
x-go-name: TokenURL
scopes:
description: >
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.
type: array
items:
$ref: '#/components/schemas/OAuth2Scope'
defaultScopes:
description: >
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.
type: array
items:
type: string
additionalAuthorizeParams:
description: >
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.
type: string
x-go-type-skip-optional-pointer: true
additionalTokenParams:
description: >
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.
type: string
x-go-type-skip-optional-pointer: true
mtlsEnabled:
type: boolean
description: >
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.
x-go-name: MTLSEnabled
x-go-type-skip-optional-pointer: true
mtlsCredentialId:
type: string
description: >
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.
x-go-name: MTLSCredentialID
grant:
$ref: '#/components/schemas/AuthSchemeConfigOAuth2Grant'
required:
- schemeType
- authorizeUrl
- tokenUrl
- scopes
- defaultScopes
- grant
AuthSchemeConfigHMAC:
description: >
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.
type: object
allOf:
- $ref: '#/components/schemas/AuthSchemeConfigBase'
- type: object
properties:
schemeType:
type: string
const: hmac
name:
type: string
description: >-
Name is the query parameter/header/cookie name which will be
used to send the signature.
in:
$ref: '#/components/schemas/AuthSchemeConfigHMACIn'
algorithm:
description: >-
AuthSchemeConfigHMACAlgorithm defines the hashing algorithm to
use when generating the HMAC signature.
type: string
enum:
- sha1
- sha256
- sha512
digestInputs:
description: >
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.
type: array
items:
type: string
enum:
- body
- url
required:
- schemeType
- name
- in
- algorithm
- digestInputs
AuthSchemeConfigCertificate:
description: >
AuthSchemeConfigCertificate is a placeholder object with the schemeType
set to `certificate`.
There is no other config required
type: object
allOf:
- $ref: '#/components/schemas/AuthSchemeConfigBase'
- type: object
properties:
schemeType:
type: string
const: certificate
required:
- schemeType
ProtocolType:
description: ProtocolType denotes the set of all valid connector types.
type: string
enum:
- http
- bigquery
Connection:
description: >
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.
type: object
properties:
id:
type: string
format: ulid
description: >
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.
x-go-name: ID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
name:
type: string
description: >-
Name is the name of the Connection. This must be unique within the
owning Connector.
credentials:
$ref: '#/components/schemas/ConnectionCredentials'
variables:
type: array
items:
$ref: '#/components/schemas/ConnectionVariable'
createdAt:
type: string
format: date-time
description: CreatedAt is the time the Connection was created.
updatedAt:
type: string
format: date-time
description: UpdatedAt is the time the Connection was last updated.
required:
- id
- name
- credentials
- variables
- createdAt
- updatedAt
ConnectorVersion:
description: ConnectorVersion represents a version of a Connector.
type: object
properties:
id:
type: string
format: ulid
description: >
ID is the unique identifier of the ConnectorVersion, this is
typically only used internally and the version
`name` is used externally in combination with the Connector `id`.
x-go-name: ID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
name:
type: string
description: >
Name denotes the actual version value for the Connector. This can be
any value but a consistent naming
strategy is recommended, such as SemVer, CalVer or an incrementing
number. The names "default" and "latest"
are reserved words and cannot be used.
description:
type: string
description: >
Description allows specifying additional information about the
ConnectorVersion, such as what changed
since the last version etc.
x-go-type-skip-optional-pointer: true
isLatest:
type: boolean
description: >-
IsLatest denotes whether this is the latest version of the
Connector.
isDefault:
type: boolean
description: >-
IsDefault denotes whether this is the default version of the
Connector.
createdAt:
type: string
format: date-time
description: CreatedAt is the time at which the ConnectorVersion was created.
updatedAt:
type: string
format: date-time
description: >
UpdatedAt is the time at which the ConnectorVersion was last
updated, including any changes to child
resources.
publishedAt:
format: date-time
description: |
PublishedAt is the time at which the ConnectorVersion was published.
type: string
nullable: true
messages:
type: array
items:
$ref: '#/components/schemas/Message'
x-go-type-skip-optional-pointer: true
required:
- id
- name
- isLatest
- isDefault
- createdAt
- updatedAt
- publishedAt
AuthSchemeConfigBase:
type: object
properties:
id:
type: string
format: ulid
description: >
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.
x-go-name: ID
description:
description: >
Description enables users to distinguish multiple configurations
which use the same
schemeType.
type: string
validationMessages:
description: >
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.
type: array
items:
$ref: '#/components/schemas/Message'
x-go-type-skip-optional-pointer: true
required:
- id
- description
AuthSchemeConfigAPIKeyIn:
description: >
AuthSchemeConfigAPIKeyIn defines the location of the API key in the
request.
type: string
enum:
- query
- header
- cookie
OAuth2Scope:
description: >
OAuth2Scope represents a single scope which can be requested by an
OAuth2 application.
type: object
properties:
name:
type: string
description: >
Name is the name of the scope as determined by the application to
which this Connector
is connecting to.
description:
type: string
description: >
Description describes the scope in human-friendly terminology. This
text may be
displayed to users via a help tooltip or similar.
x-go-type-skip-optional-pointer: true
required:
- name
AuthSchemeConfigOAuth2Grant:
type: object
discriminator:
propertyName: grantType
mapping:
authorization_code:
$ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantAuthorizationCode'
client_credentials:
$ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantClientCredentials'
password:
$ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantPassword'
oneOf:
- $ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantAuthorizationCode'
- $ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantClientCredentials'
- $ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantPassword'
AuthSchemeConfigHMACIn:
description: >-
AuthSchemeConfigHMACIn defines where the signature should be set on
requests.
type: string
enum:
- query
- header
- cookie
ConnectionCredentials:
description: >
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.
type: object
properties:
action:
type: array
items:
$ref: '#/components/schemas/ConnectionCredential'
x-go-type-skip-optional-pointer: true
trigger:
type: array
items:
$ref: '#/components/schemas/ConnectionCredential'
x-go-type-skip-optional-pointer: true
minProperties: 1
Message:
description: >
Message is a message to be displayed to the user to indicate some
information about the
preceding request.
type: object
properties:
text:
description: Text contains the text of the message.
type: string
severity:
$ref: '#/components/schemas/MessageSeverity'
detail:
description: >
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.
type: array
items:
type: string
x-go-type-skip-optional-pointer: true
required:
- text
- severity
AuthSchemeConfigOAuth2GrantAuthorizationCode:
description: >
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.
type: object
properties:
grantType:
type: string
const: authorization_code
credentialId:
description: >
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.
type: string
format: ulid
x-go-name: CredentialID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
x-go-type-skip-optional-pointer: true
organisationId:
description: >
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.
type: string
format: ulid
x-go-name: OrganisationID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
x-go-type-skip-optional-pointer: true
clientId:
description: >
ClientID is the OAuth 2.0 client's identifier. This is not a
sensitive value and may be
presented to the user in plaintext.
type: string
x-go-name: ClientID
clientSecret:
description: >
ClientSecret is the OAuth 2.0 client's secret. This is a sensitive
value and will not be
displayed to the user.
type: string
required:
- grantType
AuthSchemeConfigOAuth2GrantClientCredentials:
type: object
properties:
grantType:
type: string
const: client_credentials
required:
- grantType
AuthSchemeConfigOAuth2GrantPassword:
description: >
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.
type: object
properties:
grantType:
type: string
const: password
credentialId:
description: >
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.
type: string
format: ulid
x-go-name: CredentialID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
x-go-type-skip-optional-pointer: true
organisationId:
description: >
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.
type: string
format: ulid
x-go-name: OrganisationID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
x-go-type-skip-optional-pointer: true
clientId:
description: >
ClientID is the OAuth 2.0 client's identifier. This is not a
sensitive value and may be presented to the
user in plaintext.
type: string
x-go-name: ClientID
clientSecret:
description: >
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.
type: string
required:
- grantType
ConnectionCredential:
description: >-
ConnectionCredential contains the a Credential and the AuthSchemeConfig
to define how the Credential should be used against the Connection's
Connector.
type: object
properties:
id:
type: string
format: ulid
x-go-name: ID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
authSchemeConfig:
$ref: '#/components/schemas/AuthSchemeConfig'
credential:
$ref: '#/components/schemas/Credential'
required:
- id
- authSchemeConfig
- credential
MessageSeverity:
type: string
enum:
- info
- warning
- error
Credential:
description: >
CredentialBase is the base type for all credentials. It contains the
common properties which are shared across
all credential types.
type: object
properties:
id:
description: ID is the unique identifier of the Credential.
type: string
format: ulid
x-go-name: ID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
organisationId:
description: >-
OrganisationID is the unique identifier of the Organisation which
owns the Credential.
type: string
format: ulid
x-go-name: OrganisationID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
type:
$ref: '#/components/schemas/CredentialType'
name:
type: string
description: Name is the name of the Credential.
usages:
$ref: '#/components/schemas/CredentialUsages'
errors:
description: >
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.
type: array
items:
type: string
x-go-type-skip-optional-pointer: true
data:
oneOf:
- $ref: '#/components/schemas/CredentialDataNone'
- $ref: '#/components/schemas/CredentialDataString'
- $ref: '#/components/schemas/CredentialDataBinary'
- $ref: '#/components/schemas/CredentialDataBasicAuth'
- $ref: '#/components/schemas/CredentialDataOAuth2Client'
- $ref: '#/components/schemas/CredentialDataOAuth2Token'
- $ref: '#/components/schemas/CredentialDataOAuth2Code'
- $ref: '#/components/schemas/CredentialDataOAuth2Password'
- $ref: '#/components/schemas/CredentialDataCertificate'
expiresAt:
type: string
format: date-time
description: >
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).
required:
- id
- organisationId
- type
- name
- data
CredentialType:
description: >
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.
type: string
enum:
- none
- string
- binary
- basic-auth
- oauth2-client
- oauth2-code
- oauth2-password
- oauth2-token
- custom-function
- certificate
- jwt-bearer
x-go-type-skip-optional-pointer: true
CredentialUsages:
description: >
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.
type: array
items:
$ref: '#/components/schemas/CredentialUsage'
x-go-type-skip-optional-pointer: true
CredentialDataNone:
description: >
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.
type: object
additionalProperties: false
CredentialDataString:
description: >
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.
type: object
properties:
value:
type: string
description: >
Value is a UTF-8 string containing the credential data. When read
from the API this field will be redacted.
required:
- value
CredentialDataBinary:
description: >
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.
type: object
properties:
valueBase64:
type: string
description: >
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.
required:
- valueBase64
CredentialDataBasicAuth:
description: >
CredentialDataBasicAuth contains the username and password required to
authenticate with the Connector. The
`password` property will be redacted when returned in a response.
type: object
properties:
username:
type: string
description: Username is the username used to authenticate with the Connector.
password:
type: string
description: >
Password is the password used to authenticate with the Connector.
Will be redacted when returned in a
response.
required:
- username
- password
CredentialDataOAuth2Client:
description: >
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.
type: object
properties:
clientId:
type: string
description: >
ClientID is the OAuth2 client ID used to authenticate with the
Connector.
x-go-name: ClientID
clientSecret:
type: string
description: >
ClientSecret is the OAuth2 client secret used to authenticate with
the Connector. Will be redacted when
returned in a response.
authorizeUrl:
type: string
format: uri
description: >
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.
x-go-name: AuthorizeURL
tokenUrl:
type: string
format: uri
description: >-
TokenURL is the URL which the application will use to issue an
access token.
x-go-name: TokenURL
scopes:
type: array
items:
type: string
description: >
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.
x-go-type-skip-optional-pointer: true
additionalParams:
description: >
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.
type: string
x-go-type-skip-optional-pointer: true
mTLSEnabled:
type: boolean
description: >
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.
x-go-type-skip-optional-pointer: true
mTLSCredentialId:
type: string
description: >
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.
x-go-name: MTLSCredentialID
x-go-type-skip-optional-pointer: true
required:
- clientId
- clientSecret
- authorizeUrl
- tokenUrl
CredentialDataOAuth2Token:
description: >
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.
type: object
properties:
scopes:
type: array
items:
type: string
description: Scopes is a list of scopes which the user has granted consent for.
accessToken:
type: string
description: >
AccessToken is the OAuth2 access token which can be used to
authenticate with the Connector. This
information is redacted when read from the API.
x-go-type-skip-optional-pointer: true
refreshToken:
type: string
description: >
RefreshToken is the OAuth2 refresh token which can be used to issue
new access tokens. This information is
redacted when read from the API.
x-go-type-skip-optional-pointer: true
required:
- scopes
CredentialDataOAuth2Code:
description: >
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.
type: object
properties:
code:
description: >
Code is the authorization code which will be exchanged for an access
token.
type: string
state:
description: >
State is the state value which is propagated through the OAuth2
flow.
type: string
required:
- code
- state
CredentialDataOAuth2Password:
description: >
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.
type: object
properties:
username:
type: string
description: Username is the username used to authenticate with the Connector.
password:
type: string
description: >
Password is the password used to authenticate with the Connector.
Will be redacted when returned in a
response.
required:
- username
- password
CredentialDataCertificate:
description: >
CredentialDataCertificate contains the Certificate, Certificate key and
CA(Certificate authority).
type: object
properties:
certificate:
type: string
description: Certificate is the certificate that will be send to the connection.
key:
type: string
description: Key is the accompanying key for the certificate.
ca:
type: string
description: >-
CA is the Certificate Authority to verify the server certificates
against.
required:
- certificate
- key
- ca
CredentialUsage:
description: >
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.
type: object
properties:
connection:
$ref: '#/components/schemas/CredentialUsageConnection'
required:
- connection
CredentialUsageConnection:
description: >
CredentialUsageConnection contains the information about an Connection
which is using a Credential. This also
includes a summary of the Connector it belongs to.
type: object
properties:
id:
type: string
format: ulid
description: >
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.
x-go-name: ID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
name:
type: string
description: Name is the name of the Connection.
connector:
$ref: '#/components/schemas/ConnectorSummaryBase'
createdAt:
type: string
format: date-time
description: CreatedAt is the time the Connection was created.
updatedAt:
type: string
format: date-time
description: UpdatedAt is the time the Connection was last updated.
required:
- id
- name
- connector
- createdAt
- updatedAt
ConnectorSummaryBase:
description: >-
ConnectorSummaryBase exposes a summary of a Connector irrespective of
protocol.
type: object
properties:
id:
type: string
format: ulid
description: ID is the unique identifier of the Connector.
x-go-name: ID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
organisationId:
type: string
format: ulid
description: >-
OrganisationID is the unique identifier of the Organisation that
owns the Connector.
x-go-name: OrganisationID
name:
type: string
description: Name is the user-provided name of the Connector
protocol:
$ref: '#/components/schemas/ProtocolType'
createdAt:
type: string
format: date-time
description: CreatedAt is the time at which the ConnectorVersion was created.
updatedAt:
type: string
format: date-time
description: >
UpdatedAt is the time at which the ConnectorVersion was last
updated, including any changes to child
resources.
required:
- id
- organisationId
- name
- protocol
- createdAt
- updatedAt
securitySchemes:
bearerToken:
description: >
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.
type: http
scheme: bearer
cookie:
description: Cookie authentication used by the Versori Platform.
type: apiKey
in: cookie
name: cookie
````