Settings reference
The fields behind the admin panel's provider dialog, and the same fields as the API accepts them.
Provider
| Panel label | API field | Default | Rules |
|---|---|---|---|
| Authentication | authMode |
oauth2 |
oauth2 or api_key. With api_key, apiKey is required and the OAuth fields below are ignored |
| API key | apiKey |
none | { name, format, title, description, pattern }. name is the header, format must contain ${apiKey}, pattern is a regular expression the pasted key must match |
| Authorization URL | authorizationUrl |
required | HTTPS, no credentials, query or fragment. OAuth only |
| Token URL | tokenUrl |
required | Same. OAuth only |
| API base URL | apiBase |
required | Same, must end with /. Every proxied request must stay under this origin and path |
| PKCE | pkce |
false |
S256 |
| Token client authentication | clientAuth |
body |
body or basic |
| Scope parameter | scopeParameter |
scope |
Cannot be a reserved OAuth field |
| Authorization parameters | authorizationParams |
{} |
Extra query parameters. Cannot set client_id, client_secret, redirect_uri, response_type, state, code_challenge, code_challenge_method or the scope parameter |
| Token response path | tokenResponsePath |
empty | Dot path to the object holding access_token after code exchange |
| Refresh response path | refreshResponsePath |
empty | Same for refresh responses |
| (none) | tokenResponseMetadata |
[] |
Up to 8 dot paths copied out of the token response into the connection's metadata at exchange, refresh and reauthorization. Cannot name a credential field. API only |
| Action template | template |
none | Built-in action catalog ID |
| Display name | displayName |
none | |
| Category | category |
none |
Token responses must be JSON with a string access_token, an optional
refresh_token, a numeric expires_in and an optional string scope.
Provider and integration IDs use lowercase letters, digits, _ and -, up to
100 characters.
Integration
The admin panel saves an integration with the same ID as the provider. The API lets you create more under different IDs.
| Panel label | API field | Rules |
|---|---|---|
| (provider) | providerId |
Required |
| Client ID | clientId |
Required on create for OAuth providers; omitted on update keeps the stored value |
| Client secret | clientSecret |
Same |
| Scopes | scopes |
Required. One string in the provider's native separator; empty for API key providers |
| Webhook URL | webhookUrl |
HTTPS. null disables delivery. API only |
| Webhook secret | webhookSecret |
Set together with webhookUrl. API only |
| Signing secret | inboundSecret |
The provider's own webhook secret, used to verify inbound requests. Omit to keep, null to clear |
| Request URL | receiveId |
Read-only. The receive URL is /webhook/<receiveId> |
Connect session
| Field | Rules |
|---|---|
userId |
Required unless connectionId is given. A user created through POST /api/v1/users |
displayName |
Shown on the hosted page |
allowedIntegrations |
Integration IDs the session may connect. Omit to allow all |
connectionId |
Reauthorization mode. Owner and integration come from the connection |
expiresIn |
Milliseconds, 60 000 to 86 400 000. Default 1 800 000 (30 minutes) |
Lifecycle timings
| What | Value |
|---|---|
| Connect link validity (low-level handoff) | 10 minutes |
| Reconnect link validity | 30 minutes |
| Token refreshed before expiry | 15 minutes |
| Token refreshed at least every | 24 hours |
| Refresh retried after a failure | next UTC day, up to 4 failure days |
| Webhook delivery attempts | 3, after 3 s then 6 s |
| Action time limit | 30 seconds |
| Action provider requests limit | 50 |