Authentication
WRITE API
READ API
PLATFORM API
curl --request GET \
--url https://api.withampersand.com/v1/providers/{provider} \
--header 'X-Api-Key: <api-key>'{
"name": "<string>",
"authType": "oauth2",
"baseURL": "<string>",
"defaultModule": "<string>",
"support": {
"bulkWrite": {
"insert": true,
"update": true,
"upsert": true,
"delete": true
},
"proxy": true,
"read": true,
"subscribe": true,
"write": true,
"subscribeSupport": {
"create": true,
"update": true,
"delete": true,
"passThrough": true
},
"batchWrite": {
"delete": {
"supported": true,
"defaultRecordLimit": 123,
"objectRecordLimits": {}
},
"create": {
"supported": true,
"defaultRecordLimit": 123,
"objectRecordLimits": {}
},
"update": {
"supported": true,
"defaultRecordLimit": 123,
"objectRecordLimits": {}
},
"upsert": {
"supported": true,
"defaultRecordLimit": 123,
"objectRecordLimits": {}
}
}
},
"providerOpts": {},
"oauth2Opts": {
"grantType": "authorizationCode",
"tokenURL": "https://login.salesforce.com/services/oauth2/token",
"explicitScopesRequired": true,
"explicitWorkspaceRequired": true,
"tokenMetadataFields": {
"workspaceRefField": "account-id",
"consumerRefField": "user-id",
"scopesField": "scopes",
"otherFields": [
{
"name": "<string>",
"displayName": "<string>",
"path": "owner.siteId",
"capture": "https:\\/\\/(?<result>[^.]+)\\.docusign\\.net"
}
]
},
"authURL": "https://login.salesforce.com/services/oauth2/authorize",
"audience": [
"https://api.mparticle.com"
],
"scopeMappings": {
"default": "https://{{.workspace}}.api.com/default"
},
"docsURL": "https://docs.example.com/client-credentials",
"authURLParams": {
"access_type": "offline",
"duration": "permanent"
}
},
"apiKeyOpts": {
"attachmentType": "query",
"query": {
"name": "api_key"
},
"header": {
"name": "X-Api-Key",
"valuePrefix": "Bearer "
},
"docsURL": "https://docs.example.com/api-key"
},
"basicOpts": {
"apiKeyAsBasic": true,
"apiKeyAsBasicOpts": {
"fieldUsed": "username",
"keyFormat": "api:%s"
},
"docsURL": "https://docs.example.com/api-key"
},
"customOpts": {
"headers": [
{
"name": "X-Custom-Auth",
"valueTemplate": "Bearer {{ .token }}"
}
],
"queryParams": [
{
"name": "custom_auth",
"valueTemplate": "{{ .token }}"
}
],
"inputs": [
{
"name": "custom_auth_input",
"displayName": "Custom Auth Input",
"prompt": "See Authorization section of provider docs to obtain this value",
"docsURL": "https://docs.example.com/custom-auth-input"
}
]
},
"authHealthCheck": {
"url": "https://api.example.com/health-check",
"method": "GET",
"successStatusCodes": [
200,
204
]
},
"displayName": "Zendesk Chat",
"postAuthInfoNeeded": true,
"media": {
"regular": {
"iconURL": "https://example.com/icon.png",
"logoURL": "https://example.com/logo.png"
},
"darkMode": {
"iconURL": "https://example.com/icon.png",
"logoURL": "https://example.com/logo.png"
}
},
"labels": {},
"subscribeOpts": {
"subscriptionScope": "integration",
"targetURLScope": "integration",
"registrationTiming": "providerApp"
},
"modules": {},
"metadata": {
"input": [
{
"name": "<string>",
"displayName": "<string>",
"prompt": "<string>",
"defaultValue": "<string>",
"docsURL": "https://example.com/how-to-find-subdomain",
"moduleDependencies": {}
}
],
"postAuthentication": [
{
"name": "<string>",
"moduleDependencies": {}
}
]
}
}Get provider
curl --request GET \
--url https://api.withampersand.com/v1/providers/{provider} \
--header 'X-Api-Key: <api-key>'{
"name": "<string>",
"authType": "oauth2",
"baseURL": "<string>",
"defaultModule": "<string>",
"support": {
"bulkWrite": {
"insert": true,
"update": true,
"upsert": true,
"delete": true
},
"proxy": true,
"read": true,
"subscribe": true,
"write": true,
"subscribeSupport": {
"create": true,
"update": true,
"delete": true,
"passThrough": true
},
"batchWrite": {
"delete": {
"supported": true,
"defaultRecordLimit": 123,
"objectRecordLimits": {}
},
"create": {
"supported": true,
"defaultRecordLimit": 123,
"objectRecordLimits": {}
},
"update": {
"supported": true,
"defaultRecordLimit": 123,
"objectRecordLimits": {}
},
"upsert": {
"supported": true,
"defaultRecordLimit": 123,
"objectRecordLimits": {}
}
}
},
"providerOpts": {},
"oauth2Opts": {
"grantType": "authorizationCode",
"tokenURL": "https://login.salesforce.com/services/oauth2/token",
"explicitScopesRequired": true,
"explicitWorkspaceRequired": true,
"tokenMetadataFields": {
"workspaceRefField": "account-id",
"consumerRefField": "user-id",
"scopesField": "scopes",
"otherFields": [
{
"name": "<string>",
"displayName": "<string>",
"path": "owner.siteId",
"capture": "https:\\/\\/(?<result>[^.]+)\\.docusign\\.net"
}
]
},
"authURL": "https://login.salesforce.com/services/oauth2/authorize",
"audience": [
"https://api.mparticle.com"
],
"scopeMappings": {
"default": "https://{{.workspace}}.api.com/default"
},
"docsURL": "https://docs.example.com/client-credentials",
"authURLParams": {
"access_type": "offline",
"duration": "permanent"
}
},
"apiKeyOpts": {
"attachmentType": "query",
"query": {
"name": "api_key"
},
"header": {
"name": "X-Api-Key",
"valuePrefix": "Bearer "
},
"docsURL": "https://docs.example.com/api-key"
},
"basicOpts": {
"apiKeyAsBasic": true,
"apiKeyAsBasicOpts": {
"fieldUsed": "username",
"keyFormat": "api:%s"
},
"docsURL": "https://docs.example.com/api-key"
},
"customOpts": {
"headers": [
{
"name": "X-Custom-Auth",
"valueTemplate": "Bearer {{ .token }}"
}
],
"queryParams": [
{
"name": "custom_auth",
"valueTemplate": "{{ .token }}"
}
],
"inputs": [
{
"name": "custom_auth_input",
"displayName": "Custom Auth Input",
"prompt": "See Authorization section of provider docs to obtain this value",
"docsURL": "https://docs.example.com/custom-auth-input"
}
]
},
"authHealthCheck": {
"url": "https://api.example.com/health-check",
"method": "GET",
"successStatusCodes": [
200,
204
]
},
"displayName": "Zendesk Chat",
"postAuthInfoNeeded": true,
"media": {
"regular": {
"iconURL": "https://example.com/icon.png",
"logoURL": "https://example.com/logo.png"
},
"darkMode": {
"iconURL": "https://example.com/icon.png",
"logoURL": "https://example.com/logo.png"
}
},
"labels": {},
"subscribeOpts": {
"subscriptionScope": "integration",
"targetURLScope": "integration",
"registrationTiming": "providerApp"
},
"modules": {},
"metadata": {
"input": [
{
"name": "<string>",
"displayName": "<string>",
"prompt": "<string>",
"defaultValue": "<string>",
"docsURL": "https://example.com/how-to-find-subdomain",
"moduleDependencies": {}
}
],
"postAuthentication": [
{
"name": "<string>",
"moduleDependencies": {}
}
]
}
}Authorizations
Path Parameters
The API provider.
Response
ProviderInfo
The type of authentication required by the provider.
oauth2, apiKey, basic, jwt, custom, none The base URL for making API requests.
The supported features for the provider.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Whether this type of batch write operation is supported
The default number of records supported in a batch
Show child attributes
Show child attributes
Whether this type of batch write operation is supported
The default number of records supported in a batch
Show child attributes
Show child attributes
Whether this type of batch write operation is supported
The default number of records supported in a batch
Show child attributes
Show child attributes
Whether this type of batch write operation is supported
The default number of records supported in a batch
Configuration for OAuth2.0. Must be provided if authType is oauth2.
Show child attributes
Show child attributes
authorizationCode, authorizationCodePKCE, clientCredentials, password The token URL.
"https://login.salesforce.com/services/oauth2/token"
Whether scopes are required to be known ahead of the OAuth flow.
true
Whether the workspace is required to be known ahead of the OAuth flow.
true
Fields to be used to extract token metadata from the token response.
Show child attributes
Show child attributes
"account-id"
"user-id"
"scopes"
Additional fields to extract and transform from the token response
Show child attributes
Show child attributes
The internal name of the field
The human-readable name of the field
The path to the field in the token response (accepts dot notation for nested fields)
"owner.siteId"
A regex expression to capture the value that we need from the path. There must be only one capture group named 'result' in the expression. If not provided, will cause an error.
"https:\\/\\/(?<result>[^.]+)\\.docusign\\.net"
The authorization URL.
"https://login.salesforce.com/services/oauth2/authorize"
A list of URLs that represent the audience for the token, which is needed for some client credential grant flows.
["https://api.mparticle.com"]Maps input scopes to their full OAuth scope values with template variable support. Scopes not in this map are passed through unchanged. Needed for some providers.
Show child attributes
Show child attributes
{
"default": "https://{{.workspace}}.api.com/default"
}URL with more information about where to retrieve Client ID and Client Secret, etc.
"https://docs.example.com/client-credentials"
Configuration for API key. Must be provided if authType is apiKey.
Show child attributes
Show child attributes
How the API key should be attached to requests.
query, header Configuration for API key in header. Must be provided if type is in-header.
URL with more information about how to get or use an API key.
"https://docs.example.com/api-key"
Configuration for Basic Auth. Optional.
Show child attributes
Show child attributes
If true, the provider uses an API key which then gets encoded as a basic auth user:pass string.
true
when this object is present, it means that this provider uses Basic Auth to actually collect an API key
Show child attributes
Show child attributes
whether the API key should be used as the username or password.
username, password "username"
How to transform the API key in to a basic auth user:pass string. The %s is replaced with the API key value.
"api:%s"
URL with more information about how to get or use an API key.
"https://docs.example.com/api-key"
Configuration for custom auth. Optional.
Show child attributes
Show child attributes
A list of custom headers to be used for authentication. The backend will add these headers.
A list of custom query parameters to be used for authentication. The backend will add these query parameters.
Show child attributes
Show child attributes
A list of custom input fields for authentication. The frontend will render these input fields and the backend will receive the values of these fields before making a request.
Show child attributes
Show child attributes
The internal identifier for the custom auth input field.
"custom_auth_input"
The human-readable name for the custom auth input field.
"Custom Auth Input"
Some helpful text or context to be displayed to the user when asking for this input.
"See Authorization section of provider docs to obtain this value"
URL with details about this authentication mechanism and how to use it. Might be specific to this field, or a general URL for the provider. Optional.
"https://docs.example.com/custom-auth-input"
A URL to check the health of a provider's credentials. It's used to see if the credentials are valid and if the provider is reachable.
Show child attributes
Show child attributes
a no-op URL to check the health of the credentials. The URL MUST not mutate any state. If the provider doesn't have such an endpoint, then don't provide credentialsHealthCheck.
"https://api.example.com/health-check"
The HTTP method to use for the health check. If not set, defaults to GET.
"GET"
The HTTP status codes that indicate a successful health check. If not set, defaults to 200 and 204.
[200, 204]The display name of the provider, if omitted, defaults to provider name.
"Zendesk Chat"
If true, we require additional information after auth to start making requests.
true
Show child attributes
Show child attributes
Media to be used in dark mode.
Show child attributes
Show child attributes
The scope of the subscription.
integration, installation The scope of the target URL.
integration, installation The timing of the registration.
providerApp, integration, installation The registry of provider modules.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The supported features for the provider.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Whether this type of batch write operation is supported
The default number of records supported in a batch
Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Whether this type of batch write operation is supported
The default number of records supported in a batch
Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Whether this type of batch write operation is supported
The default number of records supported in a batch
Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Whether this type of batch write operation is supported
The default number of records supported in a batch
Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects.
Show child attributes
Show child attributes
Provider metadata that needs to be given by the user or fetched by the connector post authentication for the connector to work.
Show child attributes
Show child attributes
Metadata provided as manual input
Show child attributes
Show child attributes
The internal identifier for the metadata field
The human-readable name for the field
Human-readable description that can contain instructions on how to collect metadata
Default value for this metadata item
URL with more information about how to locate this value
"https://example.com/how-to-find-subdomain"
Metadata fetched by the connector post authentication
Show child attributes
Show child attributes
The internal identifier for the metadata field
Was this page helpful?