Generic API Connection

The Generic API connection type enables automations to call any HTTP/REST API endpoint. Rather than tying to a specific service, it provides flexible authentication and request configuration that works with any web service. It is used by the plugin-api plugin, which delegates to the api-connector.

Connection Type

The Generic API connection does not have a single dedicated ConnectionType enum entry. Instead, the plugin-api reads connection fields directly from the mandatoryFields and advancedFields maps. The authorization model is defined by the Authorization class in the API connector.

Property	Value
Category	API
Connector class	Authorization (in api-connector)

Authorization Fields

The API connector supports multiple authentication types, determined by the authType field.

Common Fields

Field	Type	Required	Description
authType	String	Yes	Authentication type. One of: No Auth, Basic Auth, Bearer Token, OAuth 2.0.

No Auth

No additional fields required. The request is sent without any authentication header.

Basic Auth

Field	Type	Required	Description
username	String	Yes	HTTP Basic Authentication username.
password	String	Yes	HTTP Basic Authentication password. Encrypted at rest.

The connector encodes username:password in Base64 and sends it as Authorization: Basic <encoded>.

Bearer Token

Field	Type	Required	Description
bearerToken	String	Yes	The bearer token value. Encrypted at rest.

Sent as Authorization: Bearer <token>.

OAuth 2.0

Field	Type	Required	Description
grantType	String	Yes	OAuth 2.0 grant type: client_credentials or password.
accessTokenGenUrl	String	Yes	Token endpoint URL (e.g., https://auth.example.com/oauth/token).
clientId	String	Yes	OAuth 2.0 client ID.
clientSecret	String	Yes	OAuth 2.0 client secret. Encrypted at rest.
scope	String	No	Space-separated list of OAuth scopes to request.
oauthUsername	String	No	Resource owner username. Required when grantType is password.
oauthPassword	String	No	Resource owner password. Required when grantType is password. Encrypted at rest.
tokenExpiry	String	No	Token TTL override in seconds. The connector caches the token until it expires.

Advanced Fields

Field	Type	Required	Description
authorizationName	String	No	Name for the authorization configuration (informational).
isAuthEditable	Boolean	No	Whether the authorization can be modified at the step level during automation design.
addToHeader	Boolean	No	Whether to add auth credentials as a request header (default behavior).
addToQueryParam	Boolean	No	Whether to add auth credentials as a query parameter instead of a header.

Token Lifecycle (OAuth 2.0)

When using OAuth 2.0, the connector:

1. Sends a POST request to accessTokenGenUrl with the client credentials and grant type.
2. Extracts the access_token from the response.
3. Attaches it as Authorization: Bearer <access_token> on subsequent API calls.
4. If tokenExpiry is set, the token is cached for that duration. Otherwise, the connector relies on the expires_in field from the token response.

Using the Connection in Automation Steps

When designing an automation step with the API plugin, you reference the connection by ID. The step configuration also includes:

• URL: The full request URL or a path that is appended to a base URL.
• Method: HTTP method (GET, POST, PUT, DELETE, PATCH).
• Headers: Additional request headers (the auth header is added automatically).
• Body: Request payload for POST/PUT/PATCH requests.
• Query Parameters: URL query parameters.

The plugin fetches the connection's decrypted authorization fields at runtime, constructs the appropriate authentication header, and sends the HTTP request through the API connector.

Friendly Example

What you enter	Example
Connection name	Vendor API - Order Status
Used for	Calling a vendor system to check order or ticket status
Main details to collect	Base URL, authentication method, token or client credentials, and timeout
Best person to provide it	Vendor owner or integration administrator

After it is saved, workflow builders select Vendor API - Order Status in a node instead of entering these details again.

Troubleshooting

Symptom	Likely Cause
401 Unauthorized	Wrong credentials, expired token, or incorrect authType
403 Forbidden	Credentials are valid but lack the required permissions/scopes
Connection refused / timeout	Target API is unreachable, or a firewall/proxy is blocking the request
OAuth token request fails	Wrong accessTokenGenUrl, clientId, or clientSecret. Verify the token endpoint independently.
SSL certificate problem	The target API uses a self-signed or internal CA certificate not trusted by the platform