curl --request PUT \
--url https://platform.versori.com/api/v2/o/{organisation_id}/connections/{connection_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"credentials": [
{
"id": "<string>",
"authSchemeConfig": {
"type": "none",
"none": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"apiKey": {
"id": "<string>",
"description": "<string>",
"name": "<string>",
"in": "query",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"basicAuth": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"oauth2": {
"id": "<string>",
"description": "<string>",
"tokenUrl": "<string>",
"scopes": [
{
"name": "<string>",
"description": "<string>"
}
],
"defaultScopes": [
"<string>"
],
"grant": {
"type": "authorizationCode",
"authorizationCode": {
"credentialId": "<string>",
"organisationId": "<string>",
"clientId": "<string>",
"clientSecret": "<string>"
},
"clientCredentials": {},
"password": {
"credentialId": "<string>",
"organisationId": "<string>",
"clientId": "<string>",
"clientSecret": "<string>"
}
},
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"authorizeUrl": "<string>",
"additionalAuthorizeParams": "<string>",
"additionalTokenParams": "<string>",
"mtlsEnabled": true,
"mtlsCredentialId": "<string>",
"pkce": true
},
"oauth1": {
"id": "<string>",
"description": "<string>",
"consumerKey": "<string>",
"consumerSecret": "<string>",
"tempCredentialEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"resourceOwnerAuthorizationEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"tokenEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"signatureMethod": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"credentialId": "<string>"
},
"hmac": {
"id": "<string>",
"description": "<string>",
"name": "<string>",
"in": "query",
"algorithm": "sha1",
"digestInputs": [
"body"
],
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"certificate": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
}
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"errors": [
"<string>"
],
"data": {
"binary": {
"valueBase64": "<string>"
},
"none": {},
"string": {
"value": "<string>"
},
"basicAuth": {
"username": "<string>",
"password": "<string>"
},
"oauth2Client": {
"clientId": "<string>",
"clientSecret": "<string>",
"tokenUrl": "<string>",
"scopes": [
"<string>"
],
"additionalParams": "<string>",
"mTLSEnabled": true,
"mTLSCredentialId": "<string>"
},
"oauth2Token": {
"scopes": [
"<string>"
],
"refreshToken": "<string>",
"accessToken": "<string>",
"tokenType": "Bearer",
"expiresAt": "2023-11-07T05:31:56Z"
},
"oauth2Code": {
"code": "<string>",
"state": "<string>"
},
"oauth2Password": {
"username": "<string>",
"password": "<string>"
},
"certificate": {
"certificate": "<string>",
"key": "<string>",
"ca": "<string>"
},
"oauth1": {
"state": "<string>",
"oauthToken": "<string>",
"oauthVerifier": "<string>"
}
},
"expiresAt": "2023-11-07T05:31:56Z"
}
}
],
"baseUrl": "<string>"
}
'{
"id": "<string>",
"name": "<string>",
"credentials": [
{
"id": "<string>",
"authSchemeConfig": {
"type": "none",
"none": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"apiKey": {
"id": "<string>",
"description": "<string>",
"name": "<string>",
"in": "query",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"basicAuth": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"oauth2": {
"id": "<string>",
"description": "<string>",
"tokenUrl": "<string>",
"scopes": [
{
"name": "<string>",
"description": "<string>"
}
],
"defaultScopes": [
"<string>"
],
"grant": {
"type": "authorizationCode",
"authorizationCode": {
"credentialId": "<string>",
"organisationId": "<string>",
"clientId": "<string>",
"clientSecret": "<string>"
},
"clientCredentials": {},
"password": {
"credentialId": "<string>",
"organisationId": "<string>",
"clientId": "<string>",
"clientSecret": "<string>"
}
},
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"authorizeUrl": "<string>",
"additionalAuthorizeParams": "<string>",
"additionalTokenParams": "<string>",
"mtlsEnabled": true,
"mtlsCredentialId": "<string>",
"pkce": true
},
"oauth1": {
"id": "<string>",
"description": "<string>",
"consumerKey": "<string>",
"consumerSecret": "<string>",
"tempCredentialEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"resourceOwnerAuthorizationEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"tokenEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"signatureMethod": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"credentialId": "<string>"
},
"hmac": {
"id": "<string>",
"description": "<string>",
"name": "<string>",
"in": "query",
"algorithm": "sha1",
"digestInputs": [
"body"
],
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"certificate": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
}
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"errors": [
"<string>"
],
"data": {
"binary": {
"valueBase64": "<string>"
},
"none": {},
"string": {
"value": "<string>"
},
"basicAuth": {
"username": "<string>",
"password": "<string>"
},
"oauth2Client": {
"clientId": "<string>",
"clientSecret": "<string>",
"tokenUrl": "<string>",
"scopes": [
"<string>"
],
"additionalParams": "<string>",
"mTLSEnabled": true,
"mTLSCredentialId": "<string>"
},
"oauth2Token": {
"scopes": [
"<string>"
],
"refreshToken": "<string>",
"accessToken": "<string>",
"tokenType": "Bearer",
"expiresAt": "2023-11-07T05:31:56Z"
},
"oauth2Code": {
"code": "<string>",
"state": "<string>"
},
"oauth2Password": {
"username": "<string>",
"password": "<string>"
},
"certificate": {
"certificate": "<string>",
"key": "<string>",
"ca": "<string>"
},
"oauth1": {
"state": "<string>",
"oauthToken": "<string>",
"oauthVerifier": "<string>"
}
},
"expiresAt": "2023-11-07T05:31:56Z"
}
}
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"baseUrl": "<string>",
"systemId": "<string>",
"connectionTemplateId": "<string>"
}Update a Connection by ID
UpdateConnection updates the Connection for the given connection ID.
curl --request PUT \
--url https://platform.versori.com/api/v2/o/{organisation_id}/connections/{connection_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"credentials": [
{
"id": "<string>",
"authSchemeConfig": {
"type": "none",
"none": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"apiKey": {
"id": "<string>",
"description": "<string>",
"name": "<string>",
"in": "query",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"basicAuth": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"oauth2": {
"id": "<string>",
"description": "<string>",
"tokenUrl": "<string>",
"scopes": [
{
"name": "<string>",
"description": "<string>"
}
],
"defaultScopes": [
"<string>"
],
"grant": {
"type": "authorizationCode",
"authorizationCode": {
"credentialId": "<string>",
"organisationId": "<string>",
"clientId": "<string>",
"clientSecret": "<string>"
},
"clientCredentials": {},
"password": {
"credentialId": "<string>",
"organisationId": "<string>",
"clientId": "<string>",
"clientSecret": "<string>"
}
},
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"authorizeUrl": "<string>",
"additionalAuthorizeParams": "<string>",
"additionalTokenParams": "<string>",
"mtlsEnabled": true,
"mtlsCredentialId": "<string>",
"pkce": true
},
"oauth1": {
"id": "<string>",
"description": "<string>",
"consumerKey": "<string>",
"consumerSecret": "<string>",
"tempCredentialEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"resourceOwnerAuthorizationEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"tokenEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"signatureMethod": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"credentialId": "<string>"
},
"hmac": {
"id": "<string>",
"description": "<string>",
"name": "<string>",
"in": "query",
"algorithm": "sha1",
"digestInputs": [
"body"
],
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"certificate": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
}
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"errors": [
"<string>"
],
"data": {
"binary": {
"valueBase64": "<string>"
},
"none": {},
"string": {
"value": "<string>"
},
"basicAuth": {
"username": "<string>",
"password": "<string>"
},
"oauth2Client": {
"clientId": "<string>",
"clientSecret": "<string>",
"tokenUrl": "<string>",
"scopes": [
"<string>"
],
"additionalParams": "<string>",
"mTLSEnabled": true,
"mTLSCredentialId": "<string>"
},
"oauth2Token": {
"scopes": [
"<string>"
],
"refreshToken": "<string>",
"accessToken": "<string>",
"tokenType": "Bearer",
"expiresAt": "2023-11-07T05:31:56Z"
},
"oauth2Code": {
"code": "<string>",
"state": "<string>"
},
"oauth2Password": {
"username": "<string>",
"password": "<string>"
},
"certificate": {
"certificate": "<string>",
"key": "<string>",
"ca": "<string>"
},
"oauth1": {
"state": "<string>",
"oauthToken": "<string>",
"oauthVerifier": "<string>"
}
},
"expiresAt": "2023-11-07T05:31:56Z"
}
}
],
"baseUrl": "<string>"
}
'{
"id": "<string>",
"name": "<string>",
"credentials": [
{
"id": "<string>",
"authSchemeConfig": {
"type": "none",
"none": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"apiKey": {
"id": "<string>",
"description": "<string>",
"name": "<string>",
"in": "query",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"basicAuth": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"oauth2": {
"id": "<string>",
"description": "<string>",
"tokenUrl": "<string>",
"scopes": [
{
"name": "<string>",
"description": "<string>"
}
],
"defaultScopes": [
"<string>"
],
"grant": {
"type": "authorizationCode",
"authorizationCode": {
"credentialId": "<string>",
"organisationId": "<string>",
"clientId": "<string>",
"clientSecret": "<string>"
},
"clientCredentials": {},
"password": {
"credentialId": "<string>",
"organisationId": "<string>",
"clientId": "<string>",
"clientSecret": "<string>"
}
},
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"authorizeUrl": "<string>",
"additionalAuthorizeParams": "<string>",
"additionalTokenParams": "<string>",
"mtlsEnabled": true,
"mtlsCredentialId": "<string>",
"pkce": true
},
"oauth1": {
"id": "<string>",
"description": "<string>",
"consumerKey": "<string>",
"consumerSecret": "<string>",
"tempCredentialEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"resourceOwnerAuthorizationEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"tokenEndpoint": {
"url": "<string>",
"additionalParamConfigs": [
{
"parameterName": "<string>",
"location": "LOCATION_IGNORE",
"required": true,
"modifiable": true,
"targetName": "<string>",
"usages": "USAGE_UNKNOWN"
}
],
"parameterTransmission": "AUTH_STYLE_AUTHORIZATION_HEADER"
},
"signatureMethod": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
],
"credentialId": "<string>"
},
"hmac": {
"id": "<string>",
"description": "<string>",
"name": "<string>",
"in": "query",
"algorithm": "sha1",
"digestInputs": [
"body"
],
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
},
"certificate": {
"id": "<string>",
"description": "<string>",
"validationMessages": [
{
"text": "<string>",
"severity": "info",
"detail": [
"<string>"
]
}
]
}
},
"credential": {
"id": "<string>",
"organisationId": "<string>",
"type": "none",
"name": "<string>",
"errors": [
"<string>"
],
"data": {
"binary": {
"valueBase64": "<string>"
},
"none": {},
"string": {
"value": "<string>"
},
"basicAuth": {
"username": "<string>",
"password": "<string>"
},
"oauth2Client": {
"clientId": "<string>",
"clientSecret": "<string>",
"tokenUrl": "<string>",
"scopes": [
"<string>"
],
"additionalParams": "<string>",
"mTLSEnabled": true,
"mTLSCredentialId": "<string>"
},
"oauth2Token": {
"scopes": [
"<string>"
],
"refreshToken": "<string>",
"accessToken": "<string>",
"tokenType": "Bearer",
"expiresAt": "2023-11-07T05:31:56Z"
},
"oauth2Code": {
"code": "<string>",
"state": "<string>"
},
"oauth2Password": {
"username": "<string>",
"password": "<string>"
},
"certificate": {
"certificate": "<string>",
"key": "<string>",
"ca": "<string>"
},
"oauth1": {
"state": "<string>",
"oauthToken": "<string>",
"oauthVerifier": "<string>"
}
},
"expiresAt": "2023-11-07T05:31:56Z"
}
}
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"baseUrl": "<string>",
"systemId": "<string>",
"connectionTemplateId": "<string>"
}Authorizations
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.
Body
ConnectionUpdate is the request payload to update an existing connection.
Name is the name of the Connection. This must be unique within the owning Connector.
ConnectionCredentials defines the credentials for the owning Connector. If multiple credentials are defined for each type, they are applied to the request in the order they are defined. This is to enable Connectors which require both a user session token and an API key to be provided in the request.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Type is a unique identifier of the AuthScheme, this is a kebab-case formatted string, see enum values for possible options.
none, api-key, basic-auth, oauth2, hmac, jwt-bearer, certificate, oauth1, secret AuthSchemeConfigNone is a placeholder object with the schemeType set to none. There is no other configuration
required.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
AuthSchemeConfigAPIKey defines how a Connector uses an API key credential to authenticate with the system.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
Name is the query parameter/header/cookie name which will be used to send the API key.
AuthSchemeConfigAPIKeyIn defines the location of the API key in the request.
query, header, cookie ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
AuthSchemeConfigBasicAuth is a placeholder object with the schemeType set to basic-auth. There is no other
configuration required.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
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.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
TokenURL is the URL which the application will use to issue an access token.
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.
Show child attributes
Show child attributes
Name is the name of the scope as determined by the application to which this Connector is connecting to.
Description describes the scope in human-friendly terminology. This text may be displayed to users via a help tooltip or similar.
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.
Show child attributes
Show child attributes
authorizationCode, clientCredentials, password 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.
Show child attributes
Show child attributes
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.
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.
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.
Show child attributes
Show child attributes
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.
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.
ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
AuthorizeURL is the URL which the user will be redirected to in order to authorize the application.
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.
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 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.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
Show child attributes
Show child attributes
URL of the endpoint, may contain templated values in curly braces
Show child attributes
Show child attributes
Key of the additional parameter to insert
LOCATION_IGNORE, LOCATION_BODY, LOCATION_HEADER, LOCATION_QUERY, LOCATION_ENDPOINT, LOCATION_HEADER_PARAMETER Whether parameter is required in requests
Whether parameter can be modified by user
Override name for the parameter in endpoint requests
USAGE_UNKNOWN, USAGE_TEMP_CREDENTIAL_ENDPOINT, USAGE_TOKEN_REQUEST_ENDPOINT AUTH_STYLE_AUTHORIZATION_HEADER, AUTH_STYLE_FORM, AUTH_STYLE_QUERY Show child attributes
Show child attributes
URL of the endpoint, may contain templated values in curly braces
Show child attributes
Show child attributes
Key of the additional parameter to insert
LOCATION_IGNORE, LOCATION_BODY, LOCATION_HEADER, LOCATION_QUERY, LOCATION_ENDPOINT, LOCATION_HEADER_PARAMETER Whether parameter is required in requests
Whether parameter can be modified by user
Override name for the parameter in endpoint requests
USAGE_UNKNOWN, USAGE_TEMP_CREDENTIAL_ENDPOINT, USAGE_TOKEN_REQUEST_ENDPOINT AUTH_STYLE_AUTHORIZATION_HEADER, AUTH_STYLE_FORM, AUTH_STYLE_QUERY Show child attributes
Show child attributes
URL of the endpoint, may contain templated values in curly braces
Show child attributes
Show child attributes
Key of the additional parameter to insert
LOCATION_IGNORE, LOCATION_BODY, LOCATION_HEADER, LOCATION_QUERY, LOCATION_ENDPOINT, LOCATION_HEADER_PARAMETER Whether parameter is required in requests
Whether parameter can be modified by user
Override name for the parameter in endpoint requests
USAGE_UNKNOWN, USAGE_TEMP_CREDENTIAL_ENDPOINT, USAGE_TOKEN_REQUEST_ENDPOINT AUTH_STYLE_AUTHORIZATION_HEADER, AUTH_STYLE_FORM, AUTH_STYLE_QUERY ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
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.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
Name is the query parameter/header/cookie name which will be used to send the signature.
AuthSchemeConfigHMACIn defines where the signature should be set on requests.
query, header, cookie AuthSchemeConfigHMACAlgorithm defines the hashing algorithm to use when generating the HMAC signature.
sha1, sha256, sha512 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.
body, url ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
AuthSchemeConfigCertificate is a placeholder object with the schemeType set to certificate.
There is no other config required
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
CredentialBase is the base type for all credentials. It contains the common properties which are shared across all credential types.
Show child attributes
Show child attributes
ID is the unique identifier of the Credential.
OrganisationID is the unique identifier of the Organisation which owns the Credential.
CredentialType denotes the type of the credential which determines what the Credential's data property will
contain.
- none: No credential is required to authenticate with the Connector.
- string: The credential is a string value, such as an API key or password.
- binary: The credential is a binary value, such as a private key, certificate or other file.
- basic-auth: The credential is a username and password to be used for basic authentication.
- oauth2-client: The credential is an OAuth2 client ID and secret to be used for OAuth2 authentication.
- oauth2-code: The credential is a temporary authorization code which will be exchanged for an oauth2-token.
- oauth2-password: The credential is an OAuth2 username and password with an optional client ID and secret to be used for OAuth2 authentication.
- oauth2-token: The credential is an OAuth2 access_token to be used for OAuth2 authentication.
- oauth1: The credential is an OAuth1 access_token to be used for OAuth1 authentication.
- certificate: The credential is a PEM encoded certificate, key and CA to be used for TLS client authentication.
none, string, binary, basic-auth, oauth2-client, oauth1, oauth2-code, oauth2-password, oauth2-token, certificate Name is the name of the Credential.
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
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.
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.
Show child attributes
Show child attributes
Value is a UTF-8 string containing the credential data. When read from the API this field will be redacted.
CredentialDataBasicAuth contains the username and password required to authenticate with the Connector. The
password property will be redacted when returned in a response.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
TokenURL is the URL which the application will use to issue an access token.
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.
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.
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.
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.
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.
Show child attributes
Show child attributes
Scopes is a list of scopes which the user has granted consent for.
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.
AccessToken is the OAuth2 access token which can be used to authenticate with the Connector. This information is redacted when read from the API.
TokenType is the type of token which is being issued. Defaults to "Bearer" if not set.
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.
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.
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.
Show child attributes
Show child attributes
Username is the username used to authenticate with the Connector.
Password is the password used to authenticate with the Connector. Will be redacted when returned in a response.
CredentialDataCertificate contains the Certificate, Certificate key and CA(Certificate authority).
Show child attributes
Show child attributes
Certificate is the certificate that will be send to the connection.
Key is the accompanying key for the certificate.
CA is the Certificate Authority to verify the server certificates against.
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).
The baseUrl on the connection allows a dynamic user to override the base URL of the connection. This is useful when users have their own instance of a service and want to connect to it.
For example, a user may have their own instance of shopify and their url is https://myshopify.com. They can
override the base url of the connection to https://myshopify.com and all requests will be made to this url.
If it is left as an empty string, it will be ignored.
Response
OK
Connection defines the credentials for the owning Connector, and additional variables which can be used to customize the Connector in a particular connection.
ID is the unique identifier of the Connection. Typically this is only used internally and most (if not all)
public-facing APIs will use the name in combination with the Connector's id instead.
Name is the name of the Connection. This must be unique within the owning Connector.
ConnectionCredentials defines the credentials for the owning Connector. If multiple credentials are defined for each type, they are applied to the request in the order they are defined. This is to enable Connectors which require both a user session token and an API key to be provided in the request.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Type is a unique identifier of the AuthScheme, this is a kebab-case formatted string, see enum values for possible options.
none, api-key, basic-auth, oauth2, hmac, jwt-bearer, certificate, oauth1, secret AuthSchemeConfigNone is a placeholder object with the schemeType set to none. There is no other configuration
required.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
AuthSchemeConfigAPIKey defines how a Connector uses an API key credential to authenticate with the system.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
Name is the query parameter/header/cookie name which will be used to send the API key.
AuthSchemeConfigAPIKeyIn defines the location of the API key in the request.
query, header, cookie ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
AuthSchemeConfigBasicAuth is a placeholder object with the schemeType set to basic-auth. There is no other
configuration required.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
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.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
TokenURL is the URL which the application will use to issue an access token.
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.
Show child attributes
Show child attributes
Name is the name of the scope as determined by the application to which this Connector is connecting to.
Description describes the scope in human-friendly terminology. This text may be displayed to users via a help tooltip or similar.
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.
Show child attributes
Show child attributes
authorizationCode, clientCredentials, password 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.
Show child attributes
Show child attributes
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.
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.
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.
Show child attributes
Show child attributes
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.
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.
ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
AuthorizeURL is the URL which the user will be redirected to in order to authorize the application.
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.
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 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.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
Show child attributes
Show child attributes
URL of the endpoint, may contain templated values in curly braces
Show child attributes
Show child attributes
Key of the additional parameter to insert
LOCATION_IGNORE, LOCATION_BODY, LOCATION_HEADER, LOCATION_QUERY, LOCATION_ENDPOINT, LOCATION_HEADER_PARAMETER Whether parameter is required in requests
Whether parameter can be modified by user
Override name for the parameter in endpoint requests
USAGE_UNKNOWN, USAGE_TEMP_CREDENTIAL_ENDPOINT, USAGE_TOKEN_REQUEST_ENDPOINT AUTH_STYLE_AUTHORIZATION_HEADER, AUTH_STYLE_FORM, AUTH_STYLE_QUERY Show child attributes
Show child attributes
URL of the endpoint, may contain templated values in curly braces
Show child attributes
Show child attributes
Key of the additional parameter to insert
LOCATION_IGNORE, LOCATION_BODY, LOCATION_HEADER, LOCATION_QUERY, LOCATION_ENDPOINT, LOCATION_HEADER_PARAMETER Whether parameter is required in requests
Whether parameter can be modified by user
Override name for the parameter in endpoint requests
USAGE_UNKNOWN, USAGE_TEMP_CREDENTIAL_ENDPOINT, USAGE_TOKEN_REQUEST_ENDPOINT AUTH_STYLE_AUTHORIZATION_HEADER, AUTH_STYLE_FORM, AUTH_STYLE_QUERY Show child attributes
Show child attributes
URL of the endpoint, may contain templated values in curly braces
Show child attributes
Show child attributes
Key of the additional parameter to insert
LOCATION_IGNORE, LOCATION_BODY, LOCATION_HEADER, LOCATION_QUERY, LOCATION_ENDPOINT, LOCATION_HEADER_PARAMETER Whether parameter is required in requests
Whether parameter can be modified by user
Override name for the parameter in endpoint requests
USAGE_UNKNOWN, USAGE_TEMP_CREDENTIAL_ENDPOINT, USAGE_TOKEN_REQUEST_ENDPOINT AUTH_STYLE_AUTHORIZATION_HEADER, AUTH_STYLE_FORM, AUTH_STYLE_QUERY ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
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.
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
Name is the query parameter/header/cookie name which will be used to send the signature.
AuthSchemeConfigHMACIn defines where the signature should be set on requests.
query, header, cookie AuthSchemeConfigHMACAlgorithm defines the hashing algorithm to use when generating the HMAC signature.
sha1, sha256, sha512 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.
body, url ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
AuthSchemeConfigCertificate is a placeholder object with the schemeType set to certificate.
There is no other config required
Show child attributes
Show child attributes
ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained.
Description enables users to distinguish multiple configurations which use the same schemeType.
ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig.
This field will be ignored if sent to the API.
Show child attributes
Show child attributes
Text contains the text of the message.
info, warning, error Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors.
CredentialBase is the base type for all credentials. It contains the common properties which are shared across all credential types.
Show child attributes
Show child attributes
ID is the unique identifier of the Credential.
OrganisationID is the unique identifier of the Organisation which owns the Credential.
CredentialType denotes the type of the credential which determines what the Credential's data property will
contain.
- none: No credential is required to authenticate with the Connector.
- string: The credential is a string value, such as an API key or password.
- binary: The credential is a binary value, such as a private key, certificate or other file.
- basic-auth: The credential is a username and password to be used for basic authentication.
- oauth2-client: The credential is an OAuth2 client ID and secret to be used for OAuth2 authentication.
- oauth2-code: The credential is a temporary authorization code which will be exchanged for an oauth2-token.
- oauth2-password: The credential is an OAuth2 username and password with an optional client ID and secret to be used for OAuth2 authentication.
- oauth2-token: The credential is an OAuth2 access_token to be used for OAuth2 authentication.
- oauth1: The credential is an OAuth1 access_token to be used for OAuth1 authentication.
- certificate: The credential is a PEM encoded certificate, key and CA to be used for TLS client authentication.
none, string, binary, basic-auth, oauth2-client, oauth1, oauth2-code, oauth2-password, oauth2-token, certificate Name is the name of the Credential.
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
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.
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.
Show child attributes
Show child attributes
Value is a UTF-8 string containing the credential data. When read from the API this field will be redacted.
CredentialDataBasicAuth contains the username and password required to authenticate with the Connector. The
password property will be redacted when returned in a response.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
TokenURL is the URL which the application will use to issue an access token.
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.
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.
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.
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.
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.
Show child attributes
Show child attributes
Scopes is a list of scopes which the user has granted consent for.
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.
AccessToken is the OAuth2 access token which can be used to authenticate with the Connector. This information is redacted when read from the API.
TokenType is the type of token which is being issued. Defaults to "Bearer" if not set.
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.
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.
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.
Show child attributes
Show child attributes
Username is the username used to authenticate with the Connector.
Password is the password used to authenticate with the Connector. Will be redacted when returned in a response.
CredentialDataCertificate contains the Certificate, Certificate key and CA(Certificate authority).
Show child attributes
Show child attributes
Certificate is the certificate that will be send to the connection.
Key is the accompanying key for the certificate.
CA is the Certificate Authority to verify the server certificates against.
ExpiresAt denotes the time this credential should be automatically deleted. External systems can subscribe to deletion events and if the reason is "expired", can trigger the correct notifications to interested parties (such as un-publishing jobs which rely on the credential and emailing the owner to rectify it).
CreatedAt is the time the Connection was created.
UpdatedAt is the time the Connection was last updated.
The baseUrl on the connection allows a dynamic user to override the base URL of the connection. This is useful when users have their own instance of a service and want to connect to it.
For example, a user may have their own instance of shopify and their url is https://myshopify.com. They can
override the base url of the connection to https://myshopify.com and all requests will be made to this url.
If it is left as an empty string, it will be ignored.
ID of the system to add the project environment.
This is the ID of the template that the connection is created against.