Connecting a Custom API
The Connection step tells Vectord where your API is and how to sign in to it. Open Sources, choose Add Source, then Other Sources → Custom API. You need to be an Owner or Admin.
The examples on these pages use a made-up helpdesk API at https://api.example.com. Replace its paths with your API's.
Connection fields
| Field | What to enter | Example |
|---|---|---|
| Display Name | How the source appears on the Sources page | Helpdesk tickets |
| API Address | The API's origin only: scheme, host and optional port, with no path | https://api.example.com |
| Authentication | How requests sign in (see below) | Bearer token |
| Records Endpoint Path | The path of the list endpoint, starting with / | /v1/tickets |
The rest of the step (the response array path, pagination, page size and fixed parameters) is on Choosing records.
Enter https://api.example.com, not https://api.example.com/v1/tickets. Paths go in Records Endpoint Path and, later, Detail Path.
Authentication
| Option | You enter | What is sent |
|---|---|---|
| No authentication | Nothing | No credentials |
| API key header | Header Name (like X-API-Key) and the key | X-API-Key: <key> on every request |
| Bearer token | The token | Authorization: Bearer <token> |
| Username and password | A username (no colon) and a password | HTTP Basic authentication |
| OAuth 2.0 | See below | Authorization: <scheme> <access token> |
Some header names can't be used for an API key: Host, Cookie, Accept, Connection, any Content-… header and other headers that control the connection itself.
OAuth 2.0
Vectord gets access tokens from your provider's token URL and renews them itself; there is no sign-in window.
| Field | What to enter |
|---|---|
| Token URL | The provider's token endpoint, without query parameters, like https://auth.example.com/oauth/token |
| Grant | Refresh token when the provider gave you a long-lived refresh token, or Client credentials for an app that signs in as itself |
| Client ID and client secret | From the app you registered with the provider |
| Refresh token | Required for the Refresh token grant |
| Scope | Optional; only if the provider asks for one |
| Client authentication | In the request body (the default) or Basic header, as the provider documents |
| Authorization scheme | The word before the token on API requests. Bearer unless your provider says otherwise; Zoho uses Zoho-oauthtoken |
Access tokens are cached encrypted with the rest of the credentials and renewed shortly before they expire. If the API answers 401, a new token is requested once. When a provider issues a new refresh token on renewal, the new one is saved.
Example: a CRM whose sign-in server differs from its API.
| Field | Value |
|---|---|
| API Address | https://www.zohoapis.com |
| Token URL | https://accounts.zoho.com/oauth/v2/token |
| Grant | Refresh token |
| Authorization scheme | Zoho-oauthtoken |
The token URL may be on a different origin from the API: token requests go only to the token URL, and data requests only to the API address. If a token response names an API host (api_domain or instance_url) different from the API address, it is refused; enter that host as the API address instead.
Allowed origins
Every request stays on the origins you entered:
- HTTPS only. The API address and the token URL must use
https://. - No leaving the origin. List requests, next-page links and detail requests must have exactly the API address's scheme, host and port. A next-page link pointing anywhere else stops the sync with a pagination error.
- No redirects. An API that answers with a redirect is refused. Use the address it redirects to.
- No private networks. The hosted app won't call private or reserved network addresses, such as
10.x.x.x,192.168.x.xorlocalhost.
A self-hosted deployment's operator can list extra origins in OUTBOUND_ALLOWED_ORIGINS, which also allows http:// and private addresses for exactly those origins. Nothing an organization enters can widen it.
Test & Continue
Test & Continue reads one sample page from the list endpoint with the credentials you entered.
- Credentials are sent once, stored encrypted and never shown again. The test session lasts 30 minutes; if it runs out, enter the credentials again.
- Nothing is saved until you connect the source on the Review step.
- If the test fails, the message says why. See Troubleshooting.
What can't change later
These fields identify the source and are shown read-only when you edit it:
- API Address, Authentication type and, for OAuth, Token URL;
- Records Endpoint Path and Response Array Path;
- Record ID, Detail Path and Detail Record Path.
To change any of them, connect a new source. Everything else can be edited; see Review required and edits.
To keep the saved credentials, leave the credential fields untouched. To replace them, open the source's gear (Edit Custom API) and enter the complete set for the authentication type: for OAuth, the client ID, the client secret and, for the refresh-token grant, the refresh token. A partial set isn't merged with what's saved.
Next: Choosing records.