Connector Tenant Configuration API
by sanjeevgiri

Connector Tenant Configuration API

Connector Tenant Configuration API
Documentation
Connector Configuration API Reference

Overview

Connector configuration API can be used to manage arbitrary configuration parameters for any Vertex/Community managed connectors for a given customer’s subscription. This API may be used connector’s customer administrator user interface.

The underlying implementation may leverage cloud provider specific solutions like AWS paramter store. However, implementation must consider compatibility with on premise deployments.

Target end users

  • Vertex connector customer adminstrators interacting with the connector configuration user interface (Human)
  • Vertex connector APIs designed for specific integration (Machine)

API Dependencies

Description of terms used

  • Client: Vertex customer
  • Tenant: Vertex customer’s subscription to a specific regional product
  • Partner Tenant: Vertex customer’s subscription for a specific partner product (Exampel - SAP US, Ariba2 Canada …)
  • Customer administrator: A user within Vertex customer’s system that can manage connector configurations.
  • Integration: An identifier for describing a machine to machine communication between partner systems and vertex core products. In Vertex Auth Service terms this may be modelled as a module.

API access

  • API endpoints can be accessed by authorized users by obtaining bearer tokens from configured idP.
  • API endpoints will be publicly available over the internet for vertex customers (Clients) that have subscriptions (Tenants) to relevant products.

Versioning

  • Current Version: 0.0.1
  • This API will be versioned using semantic versioning and will maintain backward compatibility among patch and minor versions for the given major version.

API implied defaults

  • String property size: Any model string property with undefined size may be interpreted to 255
  • Paging sort property: The default sort propery for paging is BaseResource.updatedAt field
  • Paging sort order: The default sort order is descending

Notes & Questions

  • We need to collectively define the constraints (size, optional, …) for each property. At initial design time it is intentionally relaxed and is expected to be adequetly defined at implementation time.
  • Have a decoupled broader discussion on tooling for API documentation. Remain concious to keep focus on the API during design discussion and not the API documentation tooling.
  • Vertex cloud and on demand customers must be able to login and gain access to a specific connector’s user interface? What does the idP user database look like? Is this isolated db just for connectors? Do we use existing cloud idP?

Customer administrator user interface for managing connnector configuratons

It is recommended to provide a user interface for vertex customer administrators that uses this API to manage connector configurations.

Models
BaseProblem

A Problem Details object RFC 7807

Object uri
type
string uri

A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be “about:blank”.

Example:
https://speca.io/sanjeevgiri/connector-tenant-config-api#BaseProblem
title
string

A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).

Example:
Service Unavailable
status
integer int32

The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.

Min: 400
Max: 600
exclusive
Example:
503
detail
string

A human-readable explanation specific to this occurrence of the problem.

Example:
Service Unavailable. Please try again later.
instance
string

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

Example:
connector-tenant-config-api-5868d8969f-zrz4z
timestamp
string date-time

Extention property specifying the time the problem was encountered

Example:
2022-10-28T18:39:21Z
traceId
string uuid

Extension property. Problem identifier to help querying internal log system for further details

Example:
e68cae3b-3c77-4fed-93d3-1765c24fd6e8
ecnounteredBy
string

Extension property. User or machine client that ovsreved this error.

Example:
user1@companyXyz.com
BaseResource
Object
id
string uuid

Resource identifier

Example:
9fe70c57-4815-4247-8ec8-0d886277e93a
version
integer int64

Resource version. This value is recommended to have incremental characteristics, and may be used for communicating changes over time as well as optimistic locking.

Examples:
12
createdAt
string date-time

Timestamp (UTC recommended) the resources was created.

Example:
2022-10-28T18:39:21Z
updatedAt
string date-time

Timestamp (UTC recommended) the resource was updated. For a newly created resource, this will be the same value as the createdAt property. This property may be used as the default sort field in descending order for operations that require paging across resources.

Example:
2022-10-29T18:39:21Z
createdBy
string

User identifier that initiated the creation of a given resource.

Example:
user1@companyXyz.com
updatedBy
string

User identifier that initiated the modification of a give resource. For a newly created resource, this is expected to be the same value as the createdBy property.

Example:
user2@companyXyz.com
TenantConfigPayload

Tenant config creation request.

The payload is expected to maintain logical uniqueness across following keys:

  • tenant, integration, and name
  • partnerTenant, integration, and name
Object
client
string uuid

Vertex customer internal identifier

Example:
cd671e55-9575-4a25-8b1b-2e85b5867059
clientName
string

Vertex customer name

Example:
Company xyz
tenant
string uuid

Vertex customer subscription identifier

Example:
1a855cf0-d29b-4fb2-a238-abd2c0d03856
tenantName
string
Example:
Company xyz (North America)
partnerTenant
string

Vertex customer subscription identifier in partner system. It is preferable to have uniqueness for this attribute. However, value may originate from partner system and we can assume uniqueness cannot be gauranteed by this property alone.

Example:
4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee
partnerTenantName
string
Example:
Partner 1 (North America)
integration
string uuid

Integration Identifier

Example:
8db08c8e-4474-45c9-9fba-d89e05a549ce
integrationName
string

Integration name

Example:
partner1-vertexProductAbc
group
string

Parameter group identifier.

Examples:
messageLogConfigsaccountingConfigsreportingConfigs
name
string

Configuration parameter name

Examples:
messageLogEnableddefaultSellerTaxCodedefaultConsumerTaxCode
label
string

Human readable label for this parameter

Examples:
Enable Message LoggingDefault Seller Tax Code
description
string

Human readable description for the parameter group. This may be used as communicate the detailed intent of the parameter to the end users as information texts where applicable.

Example:
This parameter is used to control message logging feature
value
string

Stringified configuratoin parameter value

Examples:
truefalseFRVAT
sensitive
boolean nullable

When set the true, the parameter value must be encrypted at rest and we recommend using encryption at flight. The user interface exposing the parameter value must mask the value using fixed characters when this property is set to true. When at rest, it is recommended to store the encryption key as well, this allows us to rotate keys during deployments and still be able to decrypt values with old key values for read operations.

Default:
false
Examples:
falsetrue
connector
Connector

Identifier for a software component that facilitates communication between partner and vertex offered service.

Example:
BIGCOMMERCE_OSERIES
show more
Example 1
{
    "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
    "clientName": "Company xyz",
    "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
    "tenantName": "Company xyz (North America)",
    "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
    "partnerTenantName": "Partner 1 (North America)",
    "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
    "integrationName": "partner1-vertexProductAbc",
    "group": "messageLogConfigs",
    "name": "defaultConsumerTaxCode",
    "label": "Enable Message Logging",
    "description": "This parameter is used to control message logging feature",
    "value": "false"
}
show more
TenantConfig

Configuration Object.

All of
BaseResource
TenantConfigPayload
Example 1
{
    "id": "9fe70c57-4815-4247-8ec8-0d886277e93a",
    "version": 2,
    "createdAt": "2022-10-28T18:39:21Z",
    "updatedAt": "2022-10-29T18:39:21Z",
    "createdBy": "user1@companyXyz.com",
    "updatedBy": "user2@companyXyz.com",
    "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
    "clientName": "Company xyz",
    "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
    "tenantName": "Company xyz (North America)",
    "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
    "partnerTenantName": "Partner 1 (North America)",
    "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
    "integrationName": "partner1-vertexProductAbc",
    "group": "reportingConfigs",
    "name": "defaultSellerTaxCode",
    "label": "Default Seller Tax Code",
    "description": "This parameter is used to control message logging feature",
    "value": "true",
    "sensitive": "false"
}
show more
TenantConfigVersion
All of
TenantConfig
Object
tenantConfig
string uuid

Reference to to the tenant configuration parameter.

Example:
71f58758-c3bb-4de8-8fe7-65f5294264af
TenantIntegration

Represents an integration between external system and vertex product for a given client’s subscription/tenant. Integrations are managed by Vertex or external community. The rollout and approval of community managed integrations is expected to be gradual and is expected to require certification guidelines.

All of
BaseResource
Object
name
string

Integration name

Example:
partnerProduct123-vertexProductAbc
client
string uuid

Vertex customer internal identifier

Example:
cd671e55-9575-4a25-8b1b-2e85b5867059
clientName
string

Vertex customer name

Example:
Company xyz
tenant
string uuid
Example:
1a855cf0-d29b-4fb2-a238-abd2c0d03856
tenantName
string
Example:
Company xyz (North America)
partnerTenant
string

Vertex customer subscription identifier in partner system. It is preferable to have uniqueness for this attribute. However, value may originate from partner system and we can assume uniqueness cannot be gauranteed by this property alone.

Example:
4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee
partnerTenantName
string
Example:
Partner product 123 for Company xyz (North America)
connector
Connector

Identifier for a software component that facilitates communication between partner and vertex offered service.

Example:
BIGCOMMERCE_OSERIES
Connector
string
Enumeration:
BIGCOMMERCE_OSERIES
SAPTAX_OSERIES
ARIBA2_OSERIES
Headers
OAuth2
Authorization
string required
Applied to all operations

OAuth2 bearer token (JSON Web Token) obtained by exchanging customer admin user credentials from the configured identity server.

Example:
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Parameters
Pagination
pageSort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. Sort order defaults to ASC when unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

/path/resource?pageSort=field1,ASC&pageSort=field2,DESC
Allow empty value: true
Default:
updatedAt,DESC
Examples:
name,ASCgroup,DESCdescription
pageSize
integer int32 optional

Requested number of elements in a given page or results

Allow empty value: true
Min: 1
Max: 100
Default:
20
pageNumber
integer int32 optional
Allow empty value: true
Default:
0
Responses
Client Problems
401 Unauthorized

Authentication failure. There was no credential attached to the request or the credential was invalid

Body
BaseProblem
Examples
{
    "type": "https://speca.io/sanjeevgiri/connector-tenant-config-api#BaseProblem",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Authentication failure. There was no credential attached to the request or the credential was invalid",
    "instance": "connector-tenant-config-api-5868d8969f-zrz4z",
    "timestamp": "2022-10-28T18:39:21Z",
    "traceId": "e68cae3b-3c77-4fed-93d3-1765c24fd6e8",
    "ecnounteredBy": "user1@companyXyz.com"
}
403 Forbidden

Authorization failure. The user or identity requesting the operation did not have the requisite role to perform the operation

Body
BaseProblem
Examples
{
    "type": "https://speca.io/sanjeevgiri/connector-tenant-config-api#BaseProblem",
    "title": "Forbidden",
    "status": 403,
    "detail": "Authorization failure. The user or identity requesting the operation did not have the requisite role to perform the operation",
    "instance": "connector-tenant-config-api-5868d8969f-zrz4z",
    "timestamp": "2022-10-28T18:39:21Z",
    "traceId": "e68cae3b-3c77-4fed-93d3-1765c24fd6e8",
    "ecnounteredBy": "user1@companyXyz.com"
}
404 Not found

The resource being read or updated does not exist

Body
BaseProblem
Examples
{
    "type": "https://speca.io/sanjeevgiri/connector-tenant-config-api#BaseProblem",
    "title": "Not Found",
    "status": 404,
    "detail": "The resource being read or updated does not exist",
    "instance": "connector-tenant-config-api-5868d8969f-zrz4z",
    "timestamp": "2022-10-28T18:39:21Z",
    "traceId": "e68cae3b-3c77-4fed-93d3-1765c24fd6e8",
    "ecnounteredBy": "user1@companyXyz.com"
}
Server Problems
500 Internal Server Error

Server encountered an unexpected condition that prevented it from fulfilling the request

Body
BaseProblem
Examples
{
    "type": "https://speca.io/sanjeevgiri/connector-tenant-config-api#BaseProblem",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "Server encountered an unexpected condition that prevented it from fulfilling the request",
    "instance": "connector-tenant-config-api-5868d8969f-zrz4z",
    "timestamp": "2022-10-28T18:39:21Z",
    "traceId": "e68cae3b-3c77-4fed-93d3-1765c24fd6e8",
    "ecnounteredBy": "user1@companyXyz.com"
}
503 Service Unavailable

Server is not ready to handle the request

Body
BaseProblem
Examples
{
    "type": "https://speca.io/sanjeevgiri/connector-tenant-config-api#BaseProblem",
    "title": "Service Unavailable",
    "status": 503,
    "detail": "Server is not ready to handle the request.",
    "instance": "connector-tenant-config-api-5868d8969f-zrz4z",
    "timestamp": "2022-10-28T18:39:21Z",
    "traceId": "e68cae3b-3c77-4fed-93d3-1765c24fd6e8",
    "ecnounteredBy": "user1@companyXyz.com"
}
Operations
Tenant Integrations (Deprecate?)

Represents an integration between external system and vertex product for a given client’s subscription/tenant.

List tenant integrations
GET /tenantintegrations
List tenant integrations
GET /tenantintegrations

Authentication

OAuth
ConnTenantConfigApi:TenantIntegration:Read

List tenant integrations for the tenants and clients associated with context user. This operation may use external apis defined in Connector Administration API fetch the results.

We may not need this indirection and connector API could interface the connector administration API directly.

Request parameters

pageSort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. Sort order defaults to ASC when unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

/path/resource?pageSort=field1,ASC&pageSort=field2,DESC
Allow empty value: true
Default:
updatedAt,DESC
Examples:
name,ASCgroup,DESCdescription
pageSize
integer int32 optional

Requested number of elements in a given page or results

Allow empty value: true
Min: 1
Max: 100
Default:
20
pageNumber
integer int32 optional
Allow empty value: true
Default:
0
connector
Connector optional

Responses

200 OK
Body
Object
content
Array of TenantIntegration
Examples
{
    "content": [
        {
            "id": "9fe70c57-4815-4247-8ec8-0d886277e93a",
            "version": 2,
            "createdAt": "2022-10-28T18:39:21Z",
            "updatedAt": "2022-10-29T18:39:21Z",
            "createdBy": "vertexConnectorAdminUser1@vertexinc.com",
            "updatedBy": "vertexConnectorAdminUser2@vertexinc.com",
            "name": "partnerProduct123-vertexProductAbc",
            "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
            "clientName": "Company xyz",
            "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
            "tenantName": "Company xyz (North America)",
            "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
            "partnerTenantName": "Partner product 123 for Company xyz (North America)"
        }
    ]
}
Manage Tenant Configurations
Create
POST /tenantintegrations/{tenantintegration}/configs
Read
GET /tenantintegrations/{tenantintegration}/configs/{config}
Update
PUT /tenantintegrations/{tenantintegration}/configs/{config}
Delete
DELETE /tenantintegrations/{tenantintegration}/configs/{config}
List
GET /tenantintegrations/{tenantintegration}/configs
List by partner tenant
GET /connectors/{connector}/partnertenants/{partnerTenant}/configs
Create
POST /tenantintegrations/{tenantintegration}/configs

Authentication

OAuth
ConnTenantConfigApi:TenantConfig:Write

Path variables

tenantintegration
string required

A valid integration associated with context user. Resource server may interact with Connector Administration API for validating user / tenant / integration association.

Request body

TenantConfigPayload
Examples

Responses

201 Created
Body
TenantConfig
401 Unauthorized

Authentication failure. There was no credential attached to the request or the credential was invalid

500 Internal Server Error

Server encountered an unexpected condition that prevented it from fulfilling the request

200
500
POST https://conn-tenant-config-public-api.platdev.vtxdev.net/tenantintegrations/1a855cf0-d29b-4fb2-a238-abd2c0d03856/configs HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
    "clientName": "Company xyz",
    "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
    "tenantName": "Company xyz (North America)",
    "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
    "partnerTenantName": "Partner 1 (North America)",
    "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
    "integrationName": "partner1-vertexProductAbc-forCompanyXyzNorthAmerica"
    "group": "messageLogConfigs",
    "name": "messageLogEnabled",
    "label": "Enable Message Logging",
    "description": "This parameter is used to control message logging feature",
    "value": "true",
    "sensitive": "false",
    "connector": "BIGCOMMERCE_OSERIES"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "9fe70c57-4815-4247-8ec8-0d886277e93a",
    "version": 0,
    "createdAt": "2022-10-28T18:39:21Z",
    "updatedAt": "2022-10-28T18:39:21Z",
    "createdBy": "user1@companyXyz.com",
    "updatedBy": "user1@companyXyz.com",
    "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
    "clientName": "Company xyz",
    "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
    "tenantName": "Company xyz (North America)",
    "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
    "partnerTenantName": "Partner 1 (North America)",
    "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
    "integrationName": "partner1-vertexProductAbc-forCompanyXyzNorthAmerica"
    "group": "messageLogConfigs",
    "name": "messageLogEnabled",
    "label": "Enable Message Logging",
    "description": "This parameter is used to control message logging feature",
    "value": "true",
    "sensitive": "false",
    "connector": "BIGCOMMERCE_OSERIES"
}
show more
POST https://conn-tenant-config-public-api.platdev.vtxdev.net/tenantintegrations/1a855cf0-d29b-4fb2-a238-abd2c0d03856/configs HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
    "clientName": "Company xyz",
    "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
    "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
    "integration": "ariba2-oseries",
    "group": "messageLogConfigs",
    "name": "messageLogEnabled",
    "label": "Enable message logging",
    "description": "This parameter is used to control message logging feature",
    "value": "true"
}

HTTP/1.1 500 Internal Server Error 

Content-Type: application/json

{
    "type": "https://speca.io/sanjeevgiri/connector-tenant-config-api#BaseProblem",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "Server encountered an unexpected condition that prevented it from fulfilling the request",
    "instance": "connector-tenant-config-api-5868d8969f-zrz4z",
    "timestamp": "2022-10-28T18:39:21Z",
    "traceId": "e68cae3b-3c77-4fed-93d3-1765c24fd6e8",
    "ecnounteredBy": "user1@companyXyz.com"
}
show more
Read
GET /tenantintegrations/{tenantintegration}/configs/{config}

Authentication

OAuth
ConnTenantConfigApi:TenantConfig:Read

Path variables

tenantintegration
string required

A valid integration associated with context user. Resource server may interact with Connector Administration API for validating user / tenant / integration association.

config
string required

Responses

200 OK
Body
TenantConfig
404 Not found

The resource being read or updated does not exist

500 Internal Server Error

Server encountered an unexpected condition that prevented it from fulfilling the request

200
404
GET https://conn-tenant-config-public-api.platdev.vtxdev.net/tenantintegrations/1a855cf0-d29b-4fb2-a238-abd2c0d03856/configs/9fe70c57-4815-4247-8ec8-0d886277e93a HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "9fe70c57-4815-4247-8ec8-0d886277e93a",
    "version": 2,
    "createdAt": "2022-10-28T18:39:21Z",
    "updatedAt": "2022-10-29T18:39:21Z",
    "createdBy": "user1@companyXyz.com",
    "updatedBy": "user2@companyXyz.com",
    "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
    "clientName": "Company xyz",
    "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
    "tenantName": "Company xyz (North America)",
    "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
    "partnerTenantName": "Partner 1 (North America)",
    "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
    "integrationName": "partner1-vertexProductAbc-forCompanyXyzNorthAmerica"
    "group": "messageLogConfigs",
    "name": "messageLogEnabled",
    "label": "Enable message logging",
    "description": "This parameter is used to control message logging feature",
    "value": "true",
    "sensitive": "true",
    "connector": "BIGCOMMERCE_OSERIES"
}
show more
GET https://conn-tenant-config-public-api.platdev.vtxdev.net/tenantintegrations/1a855cf0-d29b-4fb2-a238-abd2c0d03856/configs/9fe70c57-4815-4247-8ec8-0d886277e93a HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 404 Not Found 
{
    "type": "https://speca.io/sanjeevgiri/connector-tenant-config-api#BaseProblem",
    "title": "Not Found",
    "status": 404,
    "detail": "The resource being read or updated does not exist",
    "instance": "connector-tenant-config-api-5868d8969f-zrz4z",
    "timestamp": "2022-10-28T18:39:21Z",
    "traceId": "e68cae3b-3c77-4fed-93d3-1765c24fd6e8",
    "ecnounteredBy": "user1@companyXyz.com"
}
Content-Type: application/json
show more
Update
PUT /tenantintegrations/{tenantintegration}/configs/{config}

Authentication

OAuth
ConnTenantConfigApi:TenantConfig:Write

Path variables

tenantintegration
string required

A valid integration associated with context user. Resource server may interact with Connector Administration API for validating user / tenant / integration association.

config
string required

Request body

TenantConfigPayload

Responses

200 OK
Body
TenantConfig
404 Not found

The resource being read or updated does not exist

503 Service Unavailable

Server is not ready to handle the request

200
PUT https://conn-tenant-config-public-api.platdev.vtxdev.net/tenantintegrations/1a855cf0-d29b-4fb2-a238-abd2c0d03856/configs/9fe70c57-4815-4247-8ec8-0d886277e93a HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json

{
    "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
    "clientName": "Company xyz",
    "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
    "tenantName": "Company xyz (North America)",
    "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
    "partnerTenantName": "Partner 1 (North America)",
    "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
    "integrationName": "partner1-vertexProductAbc-forCompanyXyzNorthAmerica"
    "group": "reportingConfigs",
    "name": "messageLogEnabled",
    "label": "Enable Message Logging",
    "description": "This parameter is used to control message logging feature",
    "value": "false",
    "sensitive": "false",
    "connector": "BIGCOMMERCE_OSERIES"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "9fe70c57-4815-4247-8ec8-0d886277e93a",
    "version": 3,
    "createdAt": "2022-10-28T18:39:21Z",
    "updatedAt": "2022-10-29T18:39:21Z",
    "createdBy": "user1@companyXyz.com",
    "updatedBy": "user2@companyXyz.com",
    "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
    "clientName": "Company xyz",
    "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
    "tenantName": "Company xyz (North America)",
    "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
    "partnerTenantName": "Partner 1 (North America)",
    "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
    "integrationName": "partner1-vertexProductAbc-forCompanyXyzNorthAmerica"
    "group": "reportingConfigs",
    "name": "messageLogEnabled",
    "label": "Enable Message Logging",
    "description": "This parameter is used to control message logging feature",
    "value": "false",
    "sensitive": "false",
    "connector": "BIGCOMMERCE_OSERIES"
}
show more
Delete
DELETE /tenantintegrations/{tenantintegration}/configs/{config}

Authentication

OAuth
ConnTenantConfigApi:TenantConfig:Write

Path variables

tenantintegration
string required

A valid integration associated with context user. Resource server may interact with Connector Administration API for validating user / tenant / integration association.

config
string required

Responses

204 No Content
204
DELETE https://conn-tenant-config-public-api.platdev.vtxdev.net/tenantintegrations/1a855cf0-d29b-4fb2-a238-abd2c0d03856/configs/9fe70c57-4815-4247-8ec8-0d886277e93a HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 204 No Content
List
GET /tenantintegrations/{tenantintegration}/configs

Authentication

OAuth
ConnTenantConfigApi:TenantConfig:Read

Path variables

tenantintegration
string required

A valid integration associated with context user. Resource server may interact with Connector Administration API for validating user / tenant / integration association.

Request parameters

group
string optional
name
string optional
pageSort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. Sort order defaults to ASC when unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

/path/resource?pageSort=field1,ASC&pageSort=field2,DESC
Allow empty value: true
Default:
updatedAt,DESC
Examples:
name,ASCgroup,DESCdescription
pageSize
integer int32 optional

Requested number of elements in a given page or results

Allow empty value: true
Min: 1
Max: 100
Default:
20
pageNumber
integer int32 optional
Allow empty value: true
Default:
0

Responses

200 OK
Body
Object
content
Array of TenantConfig
200
GET https://conn-tenant-config-public-api.platdev.vtxdev.net/tenantsintegrations/1a855cf0-d29b-4fb2-a238-abd2c0d03856/configs?group=reporting HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "9fe70c57-4815-4247-8ec8-0d886277e93a",
            "version": 2,
            "createdAt": "2022-10-28T18:39:21Z",
            "updatedAt": "2022-10-29T18:39:21Z",
            "createdBy": "user1@companyXyz.com",
            "updatedBy": "user2@companyXyz.com",
            "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
            "clientName": "Company xyz",
            "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
            "tenantName": "Company xyz (North America)",
            "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
            "partnerTenantName": "Partner 1 (North America)",
            "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
            "integrationName": "partner1-vertexProductAbc-forCompanyXyzNorthAmerica"
            "group": "reporting",
            "name": "defaultConsumerTaxCode",
            "label": "Default Seller Tax Code",
            "description": "Tax code used for reporting self consumer managed tax",
            "value": "FRVAT",
            "sensitive": "false",
            "connector": "BIGCOMMERCE_OSERIES"
        }
    ]
}
show more
List by partner tenant
GET /connectors/{connector}/partnertenants/{partnerTenant}/configs

Authentication

OAuth
ConnTenantConfigApi:TenantConfig:Read

Path variables

connector
string required
partnerTenant
string required

A valid partner tenant associated with context user. Resource server may interact with Connector Administration API for validating user / partner tenant association.

Request parameters

group
string optional
name
string optional
pageSort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. Sort order defaults to ASC when unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

/path/resource?pageSort=field1,ASC&pageSort=field2,DESC
Allow empty value: true
Default:
updatedAt,DESC
Examples:
name,ASCgroup,DESCdescription
pageSize
integer int32 optional

Requested number of elements in a given page or results

Allow empty value: true
Min: 1
Max: 100
Default:
20
pageNumber
integer int32 optional
Allow empty value: true
Default:
0

Responses

200 OK
Body
Object
content
Array of TenantConfig
200
GET https://conn-tenant-config-public-api.platdev.vtxdev.net/connectors/BIGCOMMERCE_OSERIES/partnertenants/4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee/configs?group=reporting HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "9fe70c57-4815-4247-8ec8-0d886277e93a",
            "version": 2,
            "createdAt": "2022-10-28T18:39:21Z",
            "updatedAt": "2022-10-29T18:39:21Z",
            "createdBy": "user1@companyXyz.com",
            "updatedBy": "user2@companyXyz.com",
            "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
            "clientName": "Company xyz",
            "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
            "tenantName": "Company xyz (North America)",
            "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
            "partnerTenantName": "Partner 1 (North America)",
            "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
            "integrationName": "partner1-vertexProductAbc-forCompanyXyzNorthAmerica"
            "group": "reporting",
            "name": "defaultConsumerTaxCode",
            "label": "Default Seller Tax Code",
            "description": "Tax code used for reporting self consumer managed tax",
            "value": "FRVAT",
            "sensitive": "false",
            "connector": "BIGCOMMERCE_OSERIES"
        }
    ]
}
show more
Tenant Configuration Versions
List versions
GET /tenantintegrations/{tenantintegration}/configs/versions
List versions
GET /tenantintegrations/{tenantintegration}/configs/versions

Authentication

OAuth
ConnTenantConfigApi:TenantConfigVersion:Read

Path variables

tenantintegration
string required

A valid integration associated with context user. Resource server may interact with Connector Administration API for validating user / tenant / integration association.

Request parameters

group
string optional
name
string optional
pageSort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. Sort order defaults to ASC when unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

/path/resource?pageSort=field1,ASC&pageSort=field2,DESC
Allow empty value: true
Default:
updatedAt,DESC
Examples:
name,ASCgroup,DESCdescription
pageSize
integer int32 optional

Requested number of elements in a given page or results

Allow empty value: true
Min: 1
Max: 100
Default:
20
pageNumber
integer int32 optional
Allow empty value: true
Default:
0

Responses

200 OK
Body
Object
content
Array of TenantConfigVersion
200
GET https://conn-tenant-config-public-api.platdev.vtxdev.net/tenantintegrations/8db08c8e-4474-45c9-9fba-d89e05a549ce/configs?group=reporting HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "22e2c002-2a23-49ab-b8cf-e6bcecd88e4d",
            "version": 1,
            "createdAt": "2022-10-28T18:39:21Z",
            "updatedAt": "2022-10-29T18:39:21Z",
            "createdBy": "user1@companyXyz.com",
            "updatedBy": "user2@companyXyz.com",
            "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
            "clientName": "Company xyz",
            "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
            "tenantName": "Company xyz (North America)",
            "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
            "partnerTenantName": "Partner 1 (North America)",
            "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
            "integrationName": "partner1-vertexProductAbc-forCompanyXyzNorthAmerica"
            "group": "reporting",
            "name": "defaultConsumerTaxCode",
            "label": "Default Seller Tax Code",
            "description": "Tax code used for reporting self consumer managed tax",
            "value": "FRVAT",
            "sensitive": "false",
            "connector": "BIGCOMMERCE_OSERIES"
            "tenantConfig": "9fe70c57-4815-4247-8ec8-0d886277e93a"
        },
        {
            "id": "b21a387b-35b6-453b-8407-d094d31aa1f7",
            "version": 0,
            "createdAt": "2022-10-28T18:39:21Z",
            "updatedAt": "2022-10-28T18:39:21Z",
            "createdBy": "user1@companyXyz.com",
            "updatedBy": "user1@companyXyz.com",
            "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
            "clientName": "Company xyz",
            "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
            "tenantName": "Company xyz (North America)",
            "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
            "partnerTenantName": "Partner 1 (North America)",
            "integration": "8db08c8e-4474-45c9-9fba-d89e05a549ce",
            "integrationName": "partner1-vertexProductAbc-forCompanyXyzNorthAmerica"
            "group": "reporting",
            "name": "defaultConsumerTaxCode",
            "label": "Default Seller Tax Code",
            "description": "Tax code used for reporting self consumer managed tax",
            "value": "VAT",
            "sensitive": "false",
            "connector": "BIGCOMMERCE_OSERIES"
            "tenantConfig": "9fe70c57-4815-4247-8ec8-0d886277e93a"
        }
    ]
}
show more