Get provider

Returns information about a single provider. No authentication is required.

GET /providers/{provider}

Get provider

cURL

curl --request GET \
  --url https://api.withampersand.com/v1/providers/{provider}

200

{
  "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,
    "delete": true,
    "search": {
      "operators": {
        "equals": 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": {}
      }
    }
  },
  "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"
    },
    "accessTokenOpts": {
      "attachmentType": "accessTokenHeaderAttachment",
      "header": {
        "name": "X-Access-Token",
        "valuePrefix": "Bearer "
      },
      "docsURL": "https://docs.example.com/oauth2-access-token-usage"
    }
  },
  "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": {},
  "subscribeRequirements": {
    "registration": true,
    "maintenance": true,
    "postProcess": true,
    "subscribeByAPI": true
  },
  "modules": {},
  "metadata": {
    "input": [
      {
        "name": "<string>",
        "displayName": "<string>",
        "prompt": "<string>",
        "defaultValue": "<string>",
        "docsURL": "https://example.com/how-to-find-subdomain",
        "moduleDependencies": {}
      }
    ],
    "postAuthentication": [
      {
        "name": "<string>",
        "moduleDependencies": {}
      }
    ]
  },
  "providerAppMetadata": {
    "authQueryParams": [
      {
        "name": "<string>",
        "displayName": "<string>",
        "prompt": "<string>",
        "defaultValue": "<string>",
        "docsURL": "https://example.com/how-to-find-subdomain",
        "moduleDependencies": {}
      }
    ],
    "providerParams": [
      {
        "name": "<string>",
        "displayName": "<string>",
        "prompt": "<string>",
        "defaultValue": "<string>",
        "docsURL": "https://example.com/how-to-find-subdomain",
        "moduleDependencies": {}
      }
    ]
  }
}

Path Parameters

provider · string · required

The provider name (e.g. salesforce, hubspot).

Response

200

application/json

The requested provider.

name · string · required

authType · enum<string> · required

The type of authentication required by the provider.

Available options: oauth2, apiKey, basic, jwt, custom, none

baseURL · string · required

The base URL for making API requests.

defaultModule · string · required

support · Support · object · required

The supported features for the provider.

Show child attributes

oauth2Opts · OAuth2 Options · object

Configuration for OAuth2.0. Must be provided if authType is oauth2.

Show child attributes

apiKeyOpts · API Key Options · object

Configuration for API key. Must be provided if authType is apiKey.

Show child attributes

basicOpts · Basic Auth Options · object

Configuration for Basic Auth. Optional.

Show child attributes

customOpts · Custom Auth Options · object

Configuration for custom auth. Optional.

Show child attributes

authHealthCheck · Auth Health Check · object

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

displayName · string

The display name of the provider, if omitted, defaults to provider name.

Example:

"Zendesk Chat"

postAuthInfoNeeded · boolean

If true, we require additional information after auth to start making requests.

Example:

true

media · Media · object

Show child attributes

labels · Labels · object

Show child attributes

subscribeRequirements · Subscribe Requirements · object

Declares which auxiliary steps a provider requires to support subscriptions, beyond the per-object subscribe call itself.

Show child attributes

modules · Modules that this provider supports · object

The registry of provider modules.

Show child attributes

metadata · Provider Metadata · object

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

providerAppMetadata · Provider App Metadata · object

Describes the provider-app-level fields that the Ampersand dashboard should collect from the builder when creating a ProviderApp for this provider. These descriptors tell the dashboard which form fields to render; the submitted values are stored in ProviderApp.metadata.

Show child attributes