# IClients ## List iClients > Returns a list of all iClients configured in the account.\ > \ > \*\*Path casing:\*\* the API is case-insensitive — \`/v1/iClients\`, \`/v1/iclients\`,\ > and \`/v1/ICLIENTS\` all resolve to the same endpoint.\ > \ > \*\*Pagination:\*\* this endpoint does \*\*not\*\* paginate. All iClients are returned\ > in a single response with no \`Link\` header.
```json {"openapi":"3.1.0","info":{"title":"iClients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Response":{"type":"object","description":"Complete iClient object as returned by the API.\n\n**Note:** iClient responses do not include `createdAt`, `deletedAt`, or\n`_userId`. The only timestamp returned is `lastModified`.","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the iClient."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the last modification (ISO 8601, UTC)."},"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration instance ID (only present for integration-app iClients)."},"_connectorId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration app ID (only present for integration-app iClients)."}},"required":["_id"]}]},"Request":{"type":"object","description":"Configuration for iclient","required":["provider"],"properties":{"_httpConnectorId":{"type":"string","format":"objectId","description":"Specifies the unique identifier for the HTTP connector used to establish network communication. This ID links the configuration to a specific HTTP connector instance, enabling the system to route requests appropriately.\n\n**Field behavior**\n- Accepts a string representing the connector's unique ID.\n- Used to reference an existing HTTP connector configuration.\n- Required when the operation depends on a specific HTTP connector.\n- Immutable once set during the lifecycle of the configuration.\n\n**Implementation guidance**\n- Ensure the ID corresponds to a valid and active HTTP connector within the system.\n- Validate the format of the ID to match expected patterns (e.g., UUID or predefined naming conventions).\n- Use this field to dynamically select or switch HTTP connectors in multi-connector environments.\n- Handle cases where the specified connector ID does not exist or is unavailable.\n\n**Examples**\n- \"connector-1234abcd\"\n- \"http-conn-5678efgh\"\n- \"uuid-550e8400-e29b-41d4-a716-446655440000\"\n\n**Important notes**\n- This field is critical for routing HTTP requests correctly.\n- Incorrect or missing connector IDs may lead to failed connections or errors.\n- The connector ID must be managed securely to prevent unauthorized access.\n\n**Dependency chain**\n- Depends on the existence of HTTP connector configurations within the system.\n- May influence or be influenced by authentication, proxy, or network settings tied to the connector.\n\n**Technical details**\n- Typically stored as a string data type.\n- May be used as a key in lookup tables or configuration maps.\n- Should be indexed for efficient retrieval in large-scale systems."},"_httpConnectorApiId":{"type":"string","format":"objectId","description":"Specifies the unique identifier of the HTTP Connector API associated with the current configuration or operation. This ID is used to reference and link the HTTP Connector API within the system, enabling seamless integration and communication between components.\n\n**Field behavior**\n- Acts as a reference pointer to a specific HTTP Connector API instance.\n- Must be a valid and existing API identifier within the system.\n- Used to establish connections and route requests appropriately.\n- Typically immutable once set to ensure consistent API linkage.\n\n**Implementation guidance**\n- Validate the ID against the list of available HTTP Connector APIs before assignment.\n- Ensure the ID format complies with the system’s identifier standards (e.g., UUID or specific naming conventions).\n- Handle cases where the referenced API ID does not exist or is deprecated.\n- Use this property to dynamically bind or switch HTTP Connector APIs in configurations.\n\n**Examples**\n- \"api-123e4567-e89b-12d3-a456-426614174000\"\n- \"http-connector-v2\"\n- \"connectorApi_987654321\"\n\n**Important notes**\n- This property is critical for routing HTTP requests correctly.\n- Incorrect or missing IDs can lead to failed API calls or misrouted traffic.\n- Changes to this ID should be managed carefully to avoid breaking integrations.\n- May require appropriate permissions to read or modify.\n\n**Dependency chain**\n- Depends on the existence of the HTTP Connector API registry or catalog.\n- Used by components responsible for HTTP request handling and routing.\n- May influence authentication, authorization, and logging mechanisms tied to the API.\n\n**Technical details**\n- Typically stored as a string data type.\n- Should be indexed for efficient lookup in large systems.\n- May be linked to metadata describing the HTTP Connector API’s capabilities and endpoints.\n- Often integrated with API management tools or service registries."},"enableIClientReferences":{"type":"boolean","description":"Determines whether the system should enable support for iClient references, allowing integration and interaction with iClient components or services. This setting controls the activation of features that facilitate communication, data exchange, or functionality extension through iClient references.\n\n**Field behavior**\n- When set to true, iClient references are enabled, allowing the system to recognize and process iClient-related interactions.\n- When set to false, iClient references are disabled, and any related functionality will be ignored or unavailable.\n- The field typically accepts a boolean value.\n\n**Implementation guidance**\n- Enable this setting only if your application requires integration with iClient components.\n- Ensure that enabling this does not conflict with other system configurations or security policies.\n- Validate the impact on performance and compatibility when toggling this setting.\n\n**Examples**\n- true: Enables iClient references, allowing the system to interact with iClient services.\n- false: Disables iClient references, preventing any iClient-related processing.\n\n**Important notes**\n- Enabling iClient references may require additional permissions or configurations on the client or server side.\n- Disabling this feature can improve security by limiting external references but may reduce functionality.\n- Changes to this setting might require a system restart or reinitialization to take effect.\n\n**Dependency chain**\n- May depend on the presence of iClient libraries or modules within the system.\n- Could be linked to authentication or authorization settings related to client references.\n- Might interact with other integration or communication-related configuration properties.\n\n**Technical details**\n- Typically implemented as a boolean flag in the configuration.\n- Controls conditional logic paths that handle iClient reference processing.\n- May influence API endpoints, middleware behavior, or client-server communication protocols."},"formType":{"type":"string","enum":["assistant","http"],"description":"Specifies which UI form is used to configure this iClient in integrator.io.\n\n**Critical:** How this is determined in the UI\n- If `_httpConnectorId` is set, the UI uses the **assistant** form.\n- If `_httpConnectorId` is not set, the UI uses the **http** form.\n\nThe **assistant** form is used for applications where integrator.io provides a guided setup assistant to make configuration easier.\n\n**Field behavior**\n- Controls the form layout and fields displayed in the UI.\n- May affect validation and conditional rendering in the UI.\n- Must be one of: `assistant`, `http`.\n\n**Implementation guidance**\n- Prefer letting the UI default this value based on `_httpConnectorId` unless you have a specific reason to override it.\n- Use `assistant` when configuring via an iClient assistant-backed application.\n- Use `http` for the standard HTTP configuration form.\n\n**Examples**\n- `assistant`\n- `http`\n\n**Important notes**\n- The value must be lowercase (`assistant` or `http`).\n- Changing this value impacts the UI experience for configuring the iClient.\n\n**Dependency chain**\n- Depends on whether the iClient is tied to an HTTP Connector (`_httpConnectorId`).\n- Influences which UI renderer is selected for the resource.\n\n**Technical details**\n- Stored as a lowercase string enum."},"settings":{"type":"object","description":"An object containing configuration options that customize the behavior and features of the system or application. This property allows users or developers to specify various parameters, preferences, and toggles that influence how the system operates, enabling flexible and dynamic adjustments to meet different requirements.\n\n**Field behavior**\n- Accepts a structured set of key-value pairs representing different configuration settings.\n- Can include nested objects to group related settings logically.\n- Modifications to this property typically affect system behavior immediately or upon the next initialization.\n- Supports enabling or disabling features, setting thresholds, defining modes, and other customizable options.\n\n**Implementation guidance**\n- Validate the structure and data types of the settings to ensure correctness.\n- Provide default values for unspecified settings to maintain predictable behavior.\n- Allow extensibility to accommodate future settings without breaking compatibility.\n- Document each configurable option clearly to guide users in setting appropriate values.\n\n**Examples**\n- Setting a timeout duration with `\"timeout\": 3000`.\n- Configuring logging levels with `\"logging\": {\"level\": \"verbose\", \"output\": \"file\"}`.\n- Toggling feature flags such as `\"features\": {\"betaAccess\": true, \"newUI\": false}`.\n\n**Important notes**\n- Changes to settings may require system restart or reinitialization to take effect.\n- Improper configuration can lead to unexpected behavior or degraded performance.\n- Sensitive settings should be protected and validated to prevent security risks.\n- The settings object should be kept as concise as possible to avoid complexity.\n\n**Dependency chain**\n- Dependent on the system's configuration management module.\n- May influence or be influenced by user preferences and environment variables.\n- Interacts with feature toggles, access controls, and runtime parameters.\n\n**Technical details**\n- Typically represented as a JSON object or equivalent data structure.\n- Supports various data types including strings, numbers, booleans, arrays, and nested objects.\n- May be stored in configuration files, databases, or managed via APIs.\n- Should support serialization and deserialization for persistence and transmission."},"settingsForm":{"type":"object","description":"An object representing the configuration and structure of a settings form used to capture user preferences or application parameters. This form typically includes fields, validation rules, default values, and UI metadata necessary for rendering and processing the settings interface.\n\n**Field behavior**\n- Defines the layout and components of the settings form.\n- Contains input fields with associated validation and default values.\n- Supports dynamic updates based on user interaction or external data.\n- Facilitates submission and retrieval of user-configured settings.\n\n**Implementation guidance**\n- Structure the form object to include field definitions, types, labels, and validation constraints.\n- Include metadata for UI rendering such as placeholders, tooltips, and grouping.\n- Ensure validation rules are comprehensive to prevent invalid input.\n- Support extensibility to add or modify fields without breaking existing functionality.\n\n**Examples**\n- A form object with fields for username, email preferences, and notification settings.\n- A nested form structure with sections for privacy, display, and account management.\n- Validation rules specifying required fields and acceptable value ranges.\n\n**Important notes**\n- The form should be designed to accommodate localization and accessibility standards.\n- Changes to the form structure may require corresponding updates in the UI and backend processing.\n- Ensure sensitive data fields are handled securely and comply with privacy regulations.\n\n**Dependency chain**\n- Depends on UI components to render the form fields.\n- Relies on validation logic to enforce input correctness.\n- Interacts with backend services to save and retrieve settings data.\n\n**Technical details**\n- Typically represented as a JSON object or similar structured data format.\n- May include nested objects or arrays to represent complex form hierarchies.\n- Validation rules can be expressed using standard schemas or custom logic.\n- Supports integration with form libraries or frameworks for rendering and state management."},"provider":{"type":"string","enum":["google","salesforce","azureoauth","windowslive","shopify","integrator","zendesk","bigcommerce","netsuite","ebay","ebay-xml","asana","box","dropbox","clover","servicenow","jobvite","twilio","certify","dropbox","squareup","docusign","woocommerce","microsoftbusinesscentral","custom_oauth2","amazonmws"],"description":"Specifies the **authentication provider/method** used by this iClient.\n\nThis value determines which authentication flow and credential fields are used (e.g., Google OAuth, Salesforce OAuth, NetSuite token-based auth, or a custom OAuth2 provider).\n\n**Field behavior**\n- Required.\n- Must be one of the supported provider enum values.\n- Drives the UI and validation rules for which authentication settings are shown/required.\n\n**Implementation guidance**\n- Pick the provider that matches the system you are authenticating against.\n- For generic OAuth2 providers, use `custom_oauth2`.\n- Ensure the corresponding auth configuration under `oauth2`, `jwt`, or provider-specific sections is populated as needed.\n\n**Examples**\n- google\n- salesforce\n- netsuite\n- custom_oauth2\n\n**Important notes**\n- This is not a human/vendor label — it is the provider key that selects an authentication method.\n\n**Dependency chain**\n- Influences which auth sub-configurations are applicable (for example, `oauth2.*`, `netsuite.*`, `salesforce.*`, `jwt.*`).\n\n**Technical details**\n- Stored as a lowercase string enum (see the `enum` list for allowed values)."},"name":{"type":"string"},"published":{"type":"boolean","description":"Indicates whether this iClient is published (available/visible for use).\n\n**Field behavior**\n- Boolean flag: `true` or `false`.\n- Used to control publication status in the UI.\n\n**Implementation guidance**\n- Default to `false` unless you intend to publish the iClient.\n\n**Examples**\n- `true`\n- `false`"},"enableJWT":{"type":"boolean","description":"Enables use of an additional **JWT assertion** as part of an OAuth authentication flow.\n\nUse this field when the OAuth provider requires a JWT assertion as a component of the OAuth specification. When enabled, you can use the Handlebars path `{{{iClient.jwt.token}}}` to obtain the JWT token value, which is then used in the **request body of the token URL** to generate an access token.\n\n**Field behavior**\n- When `true`, the iClient includes a JWT assertion/token as part of the OAuth token request.\n- When `false`, the OAuth flow does not incorporate a JWT assertion component.\n\n**Implementation guidance**\n- Enable only when your OAuth provider requires JWT assertion.\n- Populate the `jwt` configuration (e.g., `iClient.jwt.*`) so `{{{iClient.jwt.token}}}` can be resolved.\n- Use the resolved JWT token in the token request body parameters for the OAuth token URL, as required by the provider.\n\n**Examples**\n- `true` (OAuth token request includes a JWT assertion component)\n- `false` (standard OAuth flow without JWT assertion)\n\n**Important notes**\n- This flag is for **OAuth JWT assertion** use-cases; it does not mean “all requests must include a JWT Authorization header.”\n- If enabled without configuring `iClient.jwt`, token generation will fail.\n\n**Dependency chain**\n- Depends on `iClient.jwt` fields and the provider’s OAuth token request requirements.\n- Used when constructing the token URL request body for OAuth.\n\n**Technical details**\n- The JWT token can be referenced via `{{{iClient.jwt.token}}}` during request templating."},"netsuite":{"type":"object","properties":{"consumerKey":{"type":"string","description":"The NetSuite consumer key value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `consumerKey_crypt`/`consumerKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext consumer key here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"consumerSecret":{"type":"string","description":"The NetSuite consumer secret value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `consumerSecret_crypt`/`consumerSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext consumer secret here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."}},"description":"Configuration settings and credentials required to integrate with the NetSuite platform, enabling seamless data synchronization and interaction with NetSuite's ERP and CRM services. This property typically includes authentication details, API endpoints, and any necessary parameters for establishing a secure connection.\n\n**Field behavior**\n- Holds all necessary information to authenticate and communicate with NetSuite APIs.\n- Used to configure integration settings such as account ID, role, and environment.\n- Enables data exchange between the application and NetSuite for operations like record creation, updates, and queries.\n- May support multiple authentication methods, including token-based and OAuth.\n\n**Implementation guidance**\n- Ensure sensitive credentials are stored securely and encrypted.\n- Validate all required fields before attempting connection to NetSuite.\n- Support environment-specific configurations for different environments.\n- Handle error responses gracefully to maintain integration stability.\n- Keep the configuration up to date with NetSuite API version changes.\n\n**Examples**\n- API credentials including consumer key, consumer secret, token ID, and token secret.\n- Account ID and role ID for specifying the NetSuite account and user role.\n- URLs for NetSuite REST or SOAP API endpoints.\n- Flags or settings indicating the target environment.\n\n**Important notes**\n- Incorrect or outdated credentials will prevent successful integration.\n- NetSuite API limits and governance should be considered to avoid throttling.\n- Regularly review and rotate credentials to maintain security.\n- Integration may require specific permissions within NetSuite roles.\n\n**Dependency chain**\n- Dependent on secure storage mechanisms for credentials.\n- Relies on network connectivity to NetSuite services.\n- May depend on other configuration properties like logging or retry policies.\n\n**Technical details**\n- Typically includes OAuth 1.0a or token-based authentication parameters.\n- May require JSON or XML formatted configuration data.\n- Supports both REST and SOAP API protocols depending on use case.\n- Configuration format should align with NetSuite’s API specification requirements."},"oauth2":{"type":"object","properties":{"clientId":{"type":"string","description":"The unique identifier assigned to a client application during the OAuth 2.0 registration process. This client ID is used to identify the application when making authorization requests to the OAuth 2.0 authorization server. It is a public value that is included in authorization requests and token exchanges to associate the requests with the registered client.\n\n**Field behavior**\n- Must be a unique string assigned by the authorization server.\n- Used in authorization and token request flows to identify the client application.\n- Typically remains constant for the lifetime of the client registration.\n- Should be included in all OAuth 2.0 requests where client identification is required.\n\n**Implementation guidance**\n- Obtain the client ID from the OAuth 2.0 provider during client registration.\n- Store the client ID securely within the application configuration.\n- Do not treat the client ID as a secret; it can be exposed in URLs and logs.\n- Validate the client ID format according to the OAuth provider’s specifications.\n\n**Examples**\n- \"abc123xyz\"\n- \"myapp-client-001\"\n- \"1234567890abcdef\"\n\n**Important notes**\n- The client ID is distinct from the client secret; the latter must be kept confidential.\n- Exposure of the client ID does not compromise security but is necessary for proper OAuth flows.\n- Ensure the client ID matches exactly the value registered with the OAuth provider to avoid authentication errors.\n\n**Dependency chain**\n- Dependent on successful client registration with the OAuth 2.0 authorization server.\n- Used in conjunction with client secret (if applicable) during token requests.\n- Required for constructing authorization URLs and token exchange requests.\n\n**Technical details**\n- Typically a string of alphanumeric characters, sometimes including dashes or underscores.\n- May be case-sensitive depending on the OAuth provider.\n- Passed as a query parameter or in the request body during OAuth flows.\n- Must conform to the OAuth 2.0 specification and provider-specific requirements."},"clientSecret":{"type":"string","description":"The OAuth 2.0 **client secret** value.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this secret encrypted at rest (for example as `clientSecret_crypt` and `clientSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a secret is already set.\n\n**Implementation guidance**\n- Provide the plain client secret value here to set/update it.\n- To keep the existing secret unchanged during an update, omit this field (or, if the API/UI returns a masked value, keep `\"******\"` as-is)."},"scope":{"type":"array","items":{"type":"string"},"description":"OAuth 2.0 scopes requested for the access token.\n\n**API behavior:** the API accepts a string on input but always\nreturns an **array of strings** in responses. When you send a\nspace-delimited string like `\"openid profile\"`, the response\nwraps it as `[\"openid profile\"]`.\n\n**Examples**\n- `[]`\n- `[\"openid profile email\"]`\n- `[\"read\", \"write\"]`"},"scopeDelimiter":{"type":"string","description":"Specifies the character or string used to separate multiple OAuth2 scopes within a single authorization request or token. This delimiter enables the parsing and interpretation of scope values when they are provided as a concatenated string. Common delimiters include spaces, commas, or other characters depending on the OAuth2 provider's implementation.\n\n**Field behavior**\n- Defines how multiple scopes are split and recognized in authorization requests.\n- Ensures correct parsing of scope strings when multiple scopes are requested simultaneously.\n- Influences the format of the scope parameter in OAuth2 authorization URLs and tokens.\n\n**Implementation guidance**\n- Choose a delimiter that aligns with the OAuth2 provider's specification or defaults (e.g., space is standard per OAuth2 spec).\n- Ensure consistent use of the delimiter across all OAuth2 requests and responses.\n- Validate scope strings to correctly split and handle multiple scopes using this delimiter.\n- Document the chosen delimiter clearly for developers integrating with the API.\n\n**Examples**\n- Space character (\" \") as a delimiter: \"read write delete\"\n- Comma (\",\") as a delimiter: \"read,write,delete\"\n- Semicolon (\";\") as a delimiter: \"read;write;delete\"\n\n**Important notes**\n- The OAuth2 specification (RFC 6749) recommends using a space character as the scope delimiter.\n- Some OAuth2 providers may use non-standard delimiters; this property allows customization to accommodate those cases.\n- Incorrect delimiter configuration can lead to authorization failures or incorrect scope parsing.\n- When omitted, the default delimiter is typically a space character.\n\n**Dependency chain**\n- Depends on the OAuth2 authorization server's scope formatting requirements.\n- Influences how the 'scope' parameter in authorization requests and tokens is constructed and parsed.\n- May affect downstream components that interpret or validate scopes.\n\n**Technical details**\n- Typically a single character but can be a string if supported.\n- Used in string splitting functions to parse scope lists.\n- Should be URL-encoded if it is a special character in URLs.\n- Must be consistent with the OAuth2 provider's expectations to ensure interoperability."},"redirectUri":{"type":"string","description":"The URI to which the authorization server will redirect the user-agent after granting or denying access. This URI must be registered with the authorization server and should exactly match one of the pre-registered redirect URIs to prevent security vulnerabilities such as open redirect attacks. It is used in OAuth 2.0 authorization flows to receive authorization codes or access tokens securely.\n\n**Field behavior**\n- Specifies the callback endpoint for the authorization response.\n- Must be an absolute URI.\n- Used to return authorization codes or tokens after user consent.\n- Validated against pre-registered URIs to ensure security.\n\n**Implementation guidance**\n- Ensure the redirect URI is registered with the authorization server before use.\n- Use HTTPS to protect the integrity and confidentiality of the redirect.\n- Avoid using wildcard or overly broad redirect URIs.\n- Validate the redirect URI strictly on the server side to prevent open redirect vulnerabilities.\n\n**Examples**\n- https://client.example.com/callback\n- https://app.example.com/oauth2/callback\n- https://localhost:8080/auth/callback (for development purposes)\n\n**Important notes**\n- Mismatched redirect URIs will cause authorization requests to fail.\n- Redirect URIs should not contain fragments (#).\n- Avoid using query parameters unless necessary and registered.\n- The redirect URI is critical for security; improper configuration can lead to token leakage.\n\n**Dependency chain**\n- Depends on the authorization server's registered redirect URIs.\n- Used in conjunction with client_id and response_type parameters.\n- Integral to OAuth 2.0 authorization code and implicit grant flows.\n\n**Technical details**\n- Must conform to URI syntax as per RFC 3986.\n- Typically uses HTTPS scheme for security.\n- Should be URL-encoded when included in authorization requests.\n- The authorization server compares the redirect URI in the request with the registered URIs for exact match or pattern match depending on server policy."},"clientCredentialsLocation":{"type":"string","enum":["basicauthheader","body"],"description":"Specifies the location within the HTTP request where the client credentials (such as client ID and client secret) should be included when using the OAuth 2.0 client credentials grant type. This setting determines whether the credentials are sent in the request header (typically using the Authorization header with Basic authentication) or in the request body as form parameters.\n\n**Field behavior**\n- Defines where to place client credentials during the token request.\n- Accepts values indicating header or body placement.\n- Influences how the authentication server receives and validates client credentials.\n\n**Implementation guidance**\n- Use \"header\" to send credentials via the Authorization header using Basic authentication.\n- Use \"body\" to include credentials as form parameters in the POST request body.\n- Ensure compatibility with the OAuth 2.0 server’s expected credential location.\n- Validate that the chosen location aligns with security best practices and server requirements.\n\n**Examples**\n- \"header\" — client credentials sent in the Authorization header.\n- \"body\" — client credentials sent as form parameters in the request body.\n\n**Important notes**\n- Sending credentials in the header is generally preferred for security reasons.\n- Some OAuth 2.0 servers may only support one method; verify server documentation.\n- Incorrect configuration may lead to authentication failures.\n- Avoid exposing client credentials in URLs or query parameters.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 client credentials grant type being used.\n- Works in conjunction with clientId and clientSecret properties.\n- Affects the construction of the token request sent to the authorization server.\n\n**Technical details**\n- When set to \"header\", credentials are base64-encoded and included in the Authorization header.\n- When set to \"body\", credentials are included as \"client_id\" and \"client_secret\" form parameters.\n- Must comply with the OAuth 2.0 specification (RFC 6749) regarding client authentication methods."},"validDomainNames":{"type":"array","items":{"type":"string"},"description":"A list of domain names used to validate the OAuth URLs (Authorization, Access Token, Revoke Token).\n\nProvide each unique domain once (no scheme, no path).\n\n**Examples**\n- `[\"domain.com\"]`\n- `[\"domain.com\", \"domain1.com\", \"domain2.com\"]`\n\n**Technical details**\n- Stored as an array of strings."},"grantType":{"type":"string","enum":["authorizecode","password","clientcredentials"],"description":"Specifies the OAuth 2.0 grant type used to obtain an access token from the authorization server. This parameter determines the flow of the authentication process and how the client interacts with the authorization server to request and receive tokens. Common grant types include \"authorization_code\", \"client_credentials\", \"password\", and \"refresh_token\", each serving different use cases and security considerations.\n\n**Field behavior**\n- Defines the method by which the client application requests an access token.\n- Influences the parameters required in the token request.\n- Determines the security and user interaction model of the OAuth flow.\n- Must align with the authorization server's supported grant types.\n\n**Implementation guidance**\n- Choose the grant type based on the client application's capabilities and security requirements.\n- Ensure the authorization server supports the specified grant type.\n- Validate the grant type value against the OAuth 2.0 specification and any extensions used.\n- Handle errors gracefully if an unsupported or invalid grant type is provided.\n\n**Examples**\n- \"authorization_code\" for standard web server flows involving user authorization.\n- \"client_credentials\" for machine-to-machine authentication without user involvement.\n- \"password\" for legacy applications where the user provides credentials directly.\n- \"refresh_token\" to obtain a new access token using a previously issued refresh token.\n\n**Important notes**\n- Some grant types require additional parameters (e.g., \"authorization_code\" requires a code).\n- Using the \"password\" grant type is discouraged due to security risks.\n- The choice of grant type affects the overall security posture of the application.\n- Always use secure communication channels (HTTPS) when transmitting tokens and credentials.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 authorization server configuration.\n- Influences the required request parameters and token endpoint behavior.\n- Affects client registration details and scopes granted.\n\n**Technical details**\n- Must be a string matching one of the OAuth 2.0 defined grant types or extensions.\n- Sent as a parameter in the token request payload or URL-encoded form.\n- Case-sensitive and must conform to the OAuth 2.0 specification (RFC 6749).\n- May require additional headers or parameters depending on the grant type."},"failPath":{"type":"string","description":"Path to the **auth error field** in the HTTP response body.\n\nThis field only needs to be set if the API returns a field in the HTTP response body to indicate auth errors.\nFor example, if an API returns the field `errorMessage` with the value `Auth failed`, then set this field to `errorMessage`.\n\n**Examples**\n- `errorMessage`\n- `error`\n- `errors.0.message`"},"failValues":{"type":"array","items":{"type":"string"},"description":"Values to match against the HTTP response body field identified by\n`failPath`. If any value matches, the response is treated as an\nauth failure.\n\n**Examples**\n- `[\"access_denied\", \"invalid_grant\"]`\n- `[\"error\"]`"},"failStatusCode":{"type":"number","description":"HTTP status code that indicates an OAuth2 authentication error.\n\nThis field only needs to be set if the system you are authenticating against uses a status code **other than 401** for auth errors.\nFor example, an API may return a generic `400` status code, and then use a field in the HTTP response body to indicate authentication errors.\n\n**Field behavior**\n- Determines the HTTP response status code sent upon OAuth2 failure.\n- Influences client-side error handling and user feedback.\n- Overrides default failure status codes if explicitly set.\n\n**Implementation guidance**\n- Leave unset if auth errors are returned as `401` (default behavior).\n- Set this if auth failures are returned using another status code (e.g., `400`).\n\n**Examples**\n- 401\n- 400\n\n**Important notes**\n- Setting an inappropriate status code may lead to client confusion or security risks.\n- Some clients or intermediaries may behave differently depending on the status code.\n- The status code should be accompanied by a descriptive error message in the response body.\n\n**Dependency chain**\n- Depends on OAuth2 authentication and authorization failure events.\n- Works in conjunction with error response payloads and headers.\n- May interact with logging and monitoring systems for failure tracking.\n\n**Technical details**\n- Must be an integer within the range of valid HTTP status codes (100–599).\n- Typically used in HTTP response status line.\n- Should be consistent with OAuth2 error response standards defined in RFC 6749."},"useNewAuthFailSchema":{"type":"boolean","readOnly":true,"description":"Server-managed flag indicating whether the newer auth-failure\ndetection schema is in effect. Always `true` in current API\nresponses. Do not set this field in requests."},"failures":{"type":"array","readOnly":true,"description":"Server-computed summary of the auth-failure detection rules\nderived from `failPath`, `failValues`, and `failStatusCode`.\nPresent in responses only when those fields are configured.","items":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code that triggers auth-failure detection."},"path":{"type":"string","description":"Response body path checked for failure values."},"values":{"type":"array","items":{"type":"string"},"description":"Values at `path` that indicate an auth failure."}}}},"accessTokenLocation":{"type":"string","enum":["url","header","body"],"description":"Specifies the location where the OAuth 2.0 access token should be included when making API requests. This determines how the access token is transmitted to the server, such as in the HTTP header, query parameters, or request body. Proper configuration of this field ensures that the token is sent in a manner compatible with the API's authentication requirements.\n**Field behavior**\n- Defines the method of including the access token in API requests.\n- Common values include \"header\", \"query\", or \"body\".\n- Influences how the client constructs the request for authentication.\n**Implementation guidance**\n- Verify the API specification to determine the supported token locations.\n- Use \"header\" to include the token in the Authorization header (e.g., Bearer token).\n- Use \"query\" to append the token as a URL query parameter.\n- Use \"body\" to include the token within the request payload, typically for POST requests.\n- Ensure secure transmission, especially when using query parameters.\n**Examples**\n- \"header\" — Access token sent in the Authorization header.\n- \"query\" — Access token appended as ?access_token=XYZ in the URL.\n- \"body\" — Access token included in the POST request body parameters.\n**Important notes**\n- Sending tokens in query parameters can expose them in logs or browser history; use with caution.\n- The chosen location must align with the OAuth 2.0 server's expectations.\n- Some APIs may only support one method; incorrect configuration can lead to authentication failures.\n**Dependency chain**\n- Depends on the OAuth 2.0 flow and server requirements.\n- Works in conjunction with the access token value and token type.\n- Influences request construction and security considerations.\n**Technical details**\n- When set to \"header\", typically uses the \"Authorization: Bearer \" format.\n- When set to \"query\", appends the token as a URL parameter, often named \"access_token\".\n- When set to \"body\", includes the token in the request payload, usually as a form parameter.\n- Must be handled securely to prevent token leakage."},"accessTokenHeaderName":{"type":["string","null"],"description":"Header name used to send the OAuth 2.0 access token.\n\n**Examples**\n- `Authorization` (typically with value `Bearer `)\n- `X-Access-Token`"},"accessTokenPath":{"type":"string","description":"Specifies the relative URL path on the OAuth2 authorization server where the access token request should be sent. This path is appended to the base URL of the authorization server to form the full endpoint for obtaining an access token during the OAuth2 authentication flow. It is essential for enabling clients to exchange authorization grants for access tokens securely.\n\n**Field behavior**\n- Defines the endpoint path for access token requests in the OAuth2 flow.\n- Must be a valid relative URL path starting with a forward slash (/).\n- Used during the token exchange phase after obtaining an authorization code or other grant types.\n- Typically combined with the authorization server's base URL to form the complete token endpoint URL.\n\n**Implementation guidance**\n- Ensure the path corresponds exactly to the OAuth2 server's token endpoint specification.\n- Validate that the path is correctly formatted and accessible.\n- Avoid including query parameters or fragments in this path; it should be a clean URL path.\n- Confirm compatibility with the OAuth2 server's expected token endpoint URL structure.\n\n**Examples**\n- /oauth2/token\n- /api/v1/access_token\n- /auth/token\n\n**Important notes**\n- This path is critical for the OAuth2 token exchange process; incorrect configuration will prevent successful authentication.\n- It should not include the full URL, only the path component.\n- Must align with the OAuth2 server's documentation to ensure interoperability.\n- Often used in conjunction with other OAuth2 properties like client ID, client secret, and authorization path.\n\n**Dependency chain**\n- Depends on the base URL of the OAuth2 authorization server.\n- Used alongside authorizationPath and other OAuth2 configuration properties.\n- Integral to the OAuth2 token grant process.\n\n**Technical details**\n- Expected to be a URI path string.\n- Should begin with a forward slash (/).\n- Combined with the OAuth2 server's base URL to form the full token endpoint URI.\n- Utilized in HTTP POST requests to obtain access tokens."},"refreshTokenPath":{"type":"string","description":"The relative or absolute URL path used to request a refresh token from the OAuth 2.0 authorization server. This endpoint is typically called when the current access token has expired or is about to expire, allowing the client to obtain a new access token without requiring the user to re-authenticate. The path should conform to the OAuth 2.0 specification for token refresh requests and support the necessary HTTP methods, usually POST.\n\n**Field behavior**\n- Specifies the endpoint for refreshing OAuth 2.0 access tokens.\n- Used by the client application to maintain authenticated sessions seamlessly.\n- Invoked automatically by the client when the access token expires or is near expiration.\n- Must be accessible and correctly configured on the authorization server.\n\n**Implementation guidance**\n- Ensure the path is correctly formatted as a relative or absolute URL.\n- Confirm that the authorization server supports refresh token requests at this endpoint.\n- Secure the endpoint with appropriate authentication and authorization measures.\n- Validate that the client credentials and refresh token are correctly handled during the request.\n- Handle error responses gracefully, such as invalid or expired refresh tokens.\n\n**Examples**\n- \"/oauth2/token/refresh\"\n- \"https://auth.example.com/oauth2/token\"\n- \"/api/v1/auth/refresh-token\"\n\n**Important notes**\n- This path is distinct from the initial token request endpoint.\n- The refresh token flow requires that the client has previously obtained a refresh token.\n- Not all OAuth 2.0 providers support refresh tokens; verify compatibility.\n- The endpoint must support secure communication protocols (e.g., HTTPS).\n\n**Dependency chain**\n- Depends on the existence of a valid refresh token issued during initial authentication.\n- Works in conjunction with the access token and client credentials.\n- Related to the OAuth 2.0 token endpoint configuration.\n\n**Technical details**\n- Typically uses the HTTP POST method with form-encoded parameters.\n- Requires parameters such as grant_type=refresh_token and the refresh_token itself.\n- Responses include a new access token and optionally a new refresh token.\n- Must handle scopes and token expiration as per OAuth 2.0 standards."},"scheme":{"type":"string","description":"Specifies the OAuth 2.0 authorization scheme used for securing API requests. This field defines the method by which the client obtains and presents access tokens to authenticate and authorize API calls. Common schemes include \"authorization_code\", \"implicit\", \"password\", and \"client_credentials\", each representing a different OAuth 2.0 flow tailored to various client types and security requirements.\n\n**Field behavior**\n- Determines the OAuth 2.0 flow applied for token acquisition.\n- Influences how clients interact with the authorization server.\n- Guides the expected parameters and endpoints involved in the authentication process.\n\n**Implementation guidance**\n- Choose the scheme that best fits the client application type and security context.\n- Ensure the scheme aligns with the OAuth 2.0 specification and server capabilities.\n- Clearly document the chosen scheme to aid client developers in implementation.\n\n**Examples**\n- \"authorization_code\" for server-side web applications.\n- \"implicit\" for single-page applications.\n- \"password\" for trusted applications with user credentials.\n- \"client_credentials\" for machine-to-machine authentication.\n\n**Important notes**\n- Selecting an inappropriate scheme can lead to security vulnerabilities.\n- Some schemes may require additional parameters or configurations.\n- The scheme impacts token lifecycle and refresh mechanisms.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 specification version supported.\n- Interacts with token endpoint and authorization endpoint configurations.\n- Influences client registration and credential management.\n\n**Technical details**\n- Typically represented as a string value.\n- Must conform to recognized OAuth 2.0 flow identifiers.\n- Used by client libraries to determine authentication steps."},"accessTokenParamName":{"type":"string","description":"Parameter name used when the access token is passed as a query/body parameter (instead of a header).\n\n**Examples**\n- `access_token`\n- `token`\n- `auth_token`"},"useIClientFields":{"type":"boolean","description":"Determines whether to utilize the legacy iClient-specific fields in the OAuth2 configuration instead of the standard OAuth2 fields. This option is typically used for backward compatibility with systems or integrations that rely on the older iClient field structure.\n\n**Field behavior**\n- When set to true, the system uses iClient-specific OAuth2 fields for authentication.\n- When set to false or omitted, the system defaults to standard OAuth2 fields.\n- Influences how client credentials and tokens are processed during OAuth2 flows.\n\n**Implementation guidance**\n- Enable this flag only if integrating with legacy systems requiring iClient fields.\n- Ensure that the corresponding iClient fields are properly configured when this is enabled.\n- Validate compatibility with the OAuth2 provider before enabling this option.\n\n**Examples**\n- true: Use iClient-specific fields for OAuth2 authentication.\n- false: Use standard OAuth2 fields for authentication.\n\n**Important notes**\n- Enabling this may affect interoperability with modern OAuth2 providers.\n- This setting is primarily for backward compatibility and may be deprecated in future releases.\n- Misconfiguration can lead to authentication failures.\n\n**Dependency chain**\n- Depends on the presence of iClient-specific OAuth2 fields in the configuration.\n- Affects OAuth2 token request and refresh processes.\n\n**Technical details**\n- Overrides default OAuth2 client ID, secret, and token endpoint parameters with iClient equivalents.\n- May alter request payload structure during OAuth2 token exchanges.\n- Typically used in environments where legacy iClient authentication flows are required."},"pkceCodeChallengeMethod":{"type":["string","null"],"enum":["plain","s256"],"description":"PKCE code challenge method used for the OAuth 2.0 authorization code flow (RFC 7636).\n\n**Field behavior**\n- `s256` is recommended.\n- `plain` should only be used if required by the provider.\n\n**Examples**\n- `s256`\n- `plain`"},"auth":{"type":"object","properties":{"uri":{"type":"string","description":"The URI endpoint where the OAuth 2.0 authorization server accepts authorization requests. This URI is used by clients to initiate the authorization flow, typically by redirecting the resource owner's user-agent to this address. It must be a valid HTTPS URL to ensure secure transmission of sensitive information such as authorization codes or tokens.\n\n**Field behavior**\n- Serves as the entry point for the OAuth 2.0 authorization process.\n- Used by clients to request authorization from the resource owner.\n- Typically involves redirection of the user's browser to this URI.\n- Must support standard OAuth 2.0 authorization request parameters.\n\n**Implementation guidance**\n- Ensure the URI is an HTTPS endpoint to maintain security.\n- The endpoint should conform to OAuth 2.0 specifications for authorization endpoints.\n- Validate that the URI is reachable and correctly configured to handle authorization requests.\n- Include necessary query parameters as per OAuth 2.0 standards during requests.\n\n**Examples**\n- https://authorization-server.com/oauth2/authorize\n- https://accounts.example.com/auth\n- https://login.provider.com/oauth2/auth\n\n**Important notes**\n- The URI must be registered with the OAuth 2.0 provider and match the client configuration.\n- Using HTTP instead of HTTPS is not recommended due to security risks.\n- The URI should be stable and not change frequently to avoid client misconfigurations.\n- This endpoint is distinct from the token endpoint used to exchange authorization codes for tokens.\n\n**Dependency chain**\n- Dependent on the OAuth 2.0 client configuration specifying this URI.\n- Used in conjunction with client_id, redirect_uri, response_type, and scope parameters.\n- Works alongside the token endpoint URI for completing the OAuth flow.\n\n**Technical details**\n- Must be a valid, well-formed URL.\n- Should support GET requests with query parameters for authorization requests.\n- Typically responds with redirects (HTTP 302) to the redirect_uri with authorization codes or tokens.\n- Should implement security best practices such as TLS 1.2+ and proper CORS policies."}},"description":"Specifies the authentication method and credentials required for OAuth 2.0 authorization. This property defines how the client should authenticate with the authorization server to obtain an access token. It typically includes details such as client ID, client secret, token endpoint, scopes, and grant type.\n\n**Field behavior**\n- Determines the authentication flow used in the OAuth 2.0 process.\n- Controls how credentials are presented to the authorization server.\n- Influences token acquisition and refresh mechanisms.\n- May include multiple authentication parameters depending on the grant type.\n\n**Implementation guidance**\n- Ensure all required fields for the chosen OAuth 2.0 flow are included.\n- Securely store sensitive information like client secrets.\n- Validate the format and correctness of URLs and credentials.\n- Support common grant types such as authorization code, client credentials, and password.\n- Handle token expiration and refresh logic as needed.\n\n**Examples**\n- Client credentials flow with client ID and client secret.\n- Authorization code flow with redirect URI and scopes.\n- Password grant with username and password fields.\n- Refresh token usage for renewing access tokens.\n\n**Important notes**\n- Sensitive data must be protected and not exposed in logs or error messages.\n- The authentication method must comply with OAuth 2.0 standards.\n- Misconfiguration can lead to failed authentication or security vulnerabilities.\n- Different OAuth 2.0 providers may require specific parameters or formats.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 grant type specified elsewhere in the configuration.\n- Interacts with token endpoint URLs and scope definitions.\n- May be linked to client application registration details.\n\n**Technical details**\n- Typically includes fields such as client_id, client_secret, token_url, scopes, grant_type.\n- May require encoding or encryption of credentials during transmission.\n- Supports standard OAuth 2.0 token request and response formats.\n- Should handle HTTP status codes and error responses from the authorization server."},"token":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method used to call the OAuth 2.0 token endpoint.\n\n**Important notes**\n- `POST` is most common and recommended.\n- `GET` may expose sensitive data in URLs/logs."},"uri":{"type":"string","description":"The URI (Uniform Resource Identifier) specifying the endpoint where the OAuth 2.0 token request is sent to obtain an access token. This endpoint is responsible for authenticating the client and issuing tokens according to the OAuth 2.0 protocol. It must be a valid HTTPS URL to ensure secure transmission of sensitive credentials and tokens.\n\n**Field behavior**\n- Defines the exact URL to which token requests are made during the OAuth 2.0 flow.\n- Used by clients to exchange authorization grants or refresh tokens for access tokens.\n- Must support the OAuth 2.0 token request parameters and response formats.\n- Typically accessed via HTTP POST requests.\n\n**Implementation guidance**\n- Ensure the URI is a fully qualified HTTPS URL to maintain security.\n- Confirm the endpoint supports the OAuth 2.0 token exchange specification.\n- Validate the URI format before use to prevent runtime errors.\n- Document any additional headers or parameters required by the token endpoint.\n\n**Examples**\n- https://auth.example.com/oauth2/token\n- https://login.provider.com/oauth2/v1/token\n- https://api.service.com/oauth/token\n\n**Important notes**\n- The URI must be reachable and responsive to token requests.\n- Using HTTP instead of HTTPS is discouraged due to security risks.\n- The token endpoint may require client authentication via headers or request body.\n- Changes to this URI can disrupt the OAuth 2.0 authentication flow.\n\n**Dependency chain**\n- Dependent on the OAuth 2.0 authorization server configuration.\n- Used in conjunction with client credentials and grant types.\n- Related to other OAuth 2.0 endpoints such as authorization URI and revocation URI.\n\n**Technical details**\n- Must conform to URI syntax as per RFC 3986.\n- Typically accessed using HTTP POST with content type application/x-www-form-urlencoded.\n- Responses are usually JSON objects containing access tokens and metadata.\n- May support additional OAuth 2.0 extensions like PKCE or client authentication methods."},"body":{"type":"string","description":"The body property represents the payload content sent in the HTTP request when obtaining an OAuth 2.0 token. It typically includes key-value pairs such as grant type, client credentials, authorization code, refresh token, and scope, formatted according to the OAuth 2.0 specification. This property is essential for conveying the necessary parameters to the token endpoint to successfully authenticate and receive an access token.\n\n**Field behavior**\n- Contains the data sent in the HTTP request body during the token request.\n- Must include all required parameters based on the OAuth 2.0 grant type being used.\n- Often formatted as application/x-www-form-urlencoded or JSON, depending on the API requirements.\n- Is transmitted securely over HTTPS to protect sensitive information.\n\n**Implementation guidance**\n- Ensure the body includes all mandatory fields such as grant_type, client_id, client_secret, code, redirect_uri, or refresh_token as applicable.\n- Use the correct content type header matching the body format.\n- Encode parameters properly to comply with URL encoding standards if using form-urlencoded format.\n- Validate the body content before sending to avoid malformed requests.\n\n**Examples**\n- grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback&client_id=CLIENT_ID&client_secret=CLIENT_SECRET\n- { \"grant_type\": \"refresh_token\", \"refresh_token\": \"REFRESH_TOKEN\", \"client_id\": \"CLIENT_ID\" }\n\n**Important notes**\n- The exact parameters required in the body depend on the OAuth 2.0 flow implemented (authorization code, client credentials, password, refresh token).\n- Sensitive information such as client_secret should be handled securely and never exposed in logs or client-side code.\n- The body must conform to the OAuth 2.0 specification and the authorization server’s expectations.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 grant type selected.\n- Relies on correct client credentials and authorization codes obtained from prior steps.\n- Works in conjunction with HTTP headers like Content-Type and Authorization.\n\n**Technical details**\n- Typically sent as application/x-www-form-urlencoded or application/json.\n- Must be included in the POST request to the token endpoint URL.\n- Parameters are case-sensitive and must match the OAuth 2.0 specification.\n- The server response depends on the correctness and completeness of the body content."},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the token request when obtaining an OAuth 2.0 access token. These headers allow customization of the request, such as setting content types, authorization credentials, or custom metadata required by the token endpoint. The headers should be specified as key-value pairs where the key is the header name and the value is the header content.\n\n**Field behavior**\n- Overrides or supplements default headers sent in the token request.\n- Supports multiple headers to be included simultaneously.\n- Headers are sent exactly as specified without modification.\n- Used primarily during the OAuth 2.0 token exchange process.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized as per HTTP standards.\n- Avoid including sensitive information unless required and secure.\n- Validate header values to conform to expected formats (e.g., content-type).\n- Use this field to add custom headers required by specific OAuth providers.\n\n**Examples**\n- Authorization: Basic base64(client_id:client_secret)\n- Content-Type: application/x-www-form-urlencoded\n- Custom-Header: customValue\n\n**Important notes**\n- Headers specified here apply only to the token request, not to other OAuth flows.\n- Conflicts with default headers may cause token request failures.\n- Sensitive headers should be handled securely to prevent leaks.\n- Some OAuth providers may require specific headers for successful authentication.\n\n**Dependency chain**\n- Used in conjunction with oauth2.token.url and oauth2.token.body parameters.\n- May depend on client credentials or other authentication parameters.\n- Influences the HTTP request sent to the OAuth token endpoint.\n\n**Technical details**\n- Represented as a map/dictionary of string keys and string values.\n- Transmitted as HTTP headers in the token request POST or GET.\n- Supports standard HTTP header syntax and conventions.\n- Must comply with OAuth 2.0 token endpoint requirements and HTTP protocol."}},"description":"The access token issued by the OAuth 2.0 authorization server, used to authenticate and authorize API requests on behalf of the user or client. This token is typically a string representing a bearer token that must be included in the Authorization header of HTTP requests to access protected resources. It has a limited lifetime and scope, defining the permissions granted to the client.\n\n**Field behavior**\n- Represents the credential used to access protected resources.\n- Must be included in API requests to authenticate the client.\n- Has an expiration time after which it becomes invalid.\n- May be a JWT or opaque string depending on the authorization server.\n- Should be securely stored and transmitted only over HTTPS.\n\n**Implementation guidance**\n- Ensure the token is included in the Authorization header as \"Bearer {token}\".\n- Validate the token's expiration and scope before use.\n- Refresh the token using a refresh token if supported and expired.\n- Handle token revocation and errors gracefully.\n- Avoid logging or exposing the token in client-side code or URLs.\n\n**Examples**\n- \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n- \"2YotnFZFEjr1zCsicMWpAA\"\n- \"mF_9.B5f-4.1JqM\"\n\n**Important notes**\n- The token must be kept confidential to prevent unauthorized access.\n- Tokens are typically short-lived to enhance security.\n- Different APIs may require tokens with specific scopes or claims.\n- Always use secure transport (HTTPS) when transmitting tokens.\n\n**Dependency chain**\n- Obtained after successful OAuth 2.0 authorization or token exchange.\n- May depend on client credentials, authorization code, or refresh token.\n- Used in conjunction with the Authorization header in API requests.\n\n**Technical details**\n- Usually a string encoded in JWT or opaque format.\n- Contains claims or metadata about the user and permissions.\n- Includes an expiration timestamp (exp claim in JWT).\n- May include scopes defining access rights.\n- Must conform to OAuth 2.0 and OpenID Connect standards where applicable."},"refresh":{"type":"object","properties":{"body":{"type":"string","description":"The body of the HTTP request used to refresh an OAuth 2.0 access token. This typically includes parameters such as the refresh token, client credentials, grant type, and any additional required fields as specified by the OAuth 2.0 protocol. The body must be formatted according to the content type expected by the authorization server, commonly application/x-www-form-urlencoded.\n\n**Field behavior**\n- Contains all necessary parameters to request a new access token using a refresh token.\n- Must include the \"grant_type\" parameter set to \"refresh_token\".\n- Should include the \"refresh_token\" parameter with the valid refresh token value.\n- May include client authentication parameters such as \"client_id\" and \"client_secret\" if required.\n- Sent as the payload of the HTTP POST request to the token endpoint.\n\n**Implementation guidance**\n- Ensure the body is properly URL-encoded if using application/x-www-form-urlencoded content type.\n- Validate that all required parameters are present before sending the request.\n- Follow the OAuth 2.0 specification (RFC 6749) for the exact parameter names and values.\n- Handle any additional parameters required by the specific OAuth provider.\n- Securely handle sensitive information such as client secrets and refresh tokens.\n\n**Examples**\n- grant_type=refresh_token&refresh_token=xyz123&client_id=abc&client_secret=secret\n- grant_type=refresh_token&refresh_token=def456\n\n**Important notes**\n- The refresh token must be valid and not expired or revoked.\n- The authorization server may require client authentication in the body or via other means.\n- The content type header must match the format of the body (e.g., application/x-www-form-urlencoded).\n- Improper formatting or missing parameters will result in an error response from the server.\n\n**Dependency chain**\n- Depends on having a valid refresh token obtained from a previous authorization.\n- Requires knowledge of the OAuth 2.0 token endpoint URL.\n- May depend on client credentials if the server requires client authentication.\n- Relies on the correct grant_type parameter to indicate a refresh token request.\n\n**Technical details**\n- Typically sent as an HTTP POST request body.\n- Commonly uses application/x-www-form-urlencoded encoding.\n- Parameters include \"grant_type\", \"refresh_token\", and optionally \"client_id\" and \"client_secret\".\n- Must comply with OAuth 2.0 RFC 6749 Section 6 for token refresh requests."},"method":{"type":"string","enum":["GET","POST"],"description":"Specifies the HTTP method to be used when making the refresh token request in the OAuth 2.0 authentication flow. This method determines how the refresh token and related parameters are sent to the authorization server to obtain a new access token. Common HTTP methods include POST and GET, with POST being the most widely used due to its ability to securely transmit data in the request body.\n\n**Field behavior**\n- Defines the HTTP verb for the token refresh request.\n- Influences how parameters are encoded and transmitted.\n- Affects compatibility with different OAuth 2.0 server implementations.\n\n**Implementation guidance**\n- Typically set to POST for secure transmission of sensitive data.\n- Ensure the chosen method aligns with the OAuth 2.0 server’s requirements.\n- Validate that the client library or HTTP client supports the specified method.\n- Consider security implications of using GET, as parameters may be exposed in URLs.\n\n**Examples**\n- POST\n- GET\n\n**Important notes**\n- Using GET may expose refresh tokens in URLs, which can be logged or cached.\n- Some OAuth 2.0 servers may only support POST for token refresh requests.\n- The method must be consistent with the server’s expected protocol to avoid errors.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 server’s token endpoint configuration.\n- Interacts with the refresh token and client credentials parameters.\n- Influences the HTTP headers and body formatting of the request.\n\n**Technical details**\n- HTTP methods are case-insensitive but typically uppercase.\n- POST requests send parameters in the request body using application/x-www-form-urlencoded format.\n- GET requests send parameters as URL query parameters.\n- Proper handling of HTTP status codes and responses is required based on the method used."},"uri":{"type":"string","description":"Refresh token endpoint URI used to exchange a refresh token for a new access token (RFC 6749 Section 6).\n\n**Examples**\n- https://auth.example.com/oauth2/token\n- https://login.provider.com/oauth2/v1/token"},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the OAuth 2.0 refresh token request. These headers can be used to pass additional metadata, authentication information, or custom parameters required by the authorization server during the token refresh process. Typically, this may include headers such as `Content-Type`, `Authorization`, or any other custom headers mandated by the API specification.\n\n**Field behavior**\n- Accepts key-value pairs representing HTTP header names and their corresponding values.\n- Headers are included in the HTTP request sent to the token endpoint during the refresh token flow.\n- Overrides or supplements default headers set by the client or HTTP library.\n- Supports standard and custom headers as required by the OAuth 2.0 provider.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized and conform to HTTP standards.\n- Avoid including sensitive information in headers unless required and secured.\n- Validate header values to prevent injection or formatting errors.\n- Use this field to add headers like `Authorization` if the token endpoint requires client authentication via headers.\n- Do not duplicate headers that are automatically managed by the HTTP client unless overriding is necessary.\n\n**Examples**\n- `Content-Type: application/x-www-form-urlencoded`\n- `Authorization: Basic base64(client_id:client_secret)`\n- `Custom-Header: customValue`\n\n**Important notes**\n- Headers specified here apply only to the refresh token request, not to other OAuth 2.0 flows.\n- Misconfigured headers can cause token refresh failures or security issues.\n- Some OAuth 2.0 servers require specific headers for token refresh requests; consult the provider’s documentation.\n- Sensitive headers should be handled securely to prevent exposure.\n\n**Dependency chain**\n- Used in conjunction with `oauth2.refresh.tokenUrl` to make the refresh token request.\n- May depend on client authentication method specified elsewhere in the OAuth 2.0 configuration.\n- Interacts with HTTP client settings that manage default headers.\n\n**Technical details**\n- Represented as a map/dictionary of string keys and string values.\n- Translated into HTTP headers in the outgoing POST request to the token endpoint.\n- Must comply with HTTP/1.1 header field syntax and encoding rules.\n- Typically sent over HTTPS to ensure confidentiality and integrity."}},"description":"Indicates whether the OAuth2 refresh token flow is supported/enabled.\n\n**Examples**\n- `true`\n- `false`"},"revoke":{"type":"object","properties":{"uri":{"type":"string","description":"The URI endpoint where OAuth 2.0 token revocation requests are sent. This URI is used by clients to invalidate access or refresh tokens, ensuring they can no longer be used for authentication or authorization. It must be a valid HTTPS URL to guarantee secure transmission of sensitive token data.\n\n**Field behavior**\n- Accepts a single string value representing the revocation endpoint URL.\n- Used by clients to send HTTP POST requests to revoke tokens.\n- Should support standard OAuth 2.0 token revocation parameters as per RFC 7009.\n- Must be reachable and respond appropriately to revocation requests.\n\n**Implementation guidance**\n- Ensure the URI uses HTTPS to protect token data during transmission.\n- The endpoint should conform to OAuth 2.0 Token Revocation specification (RFC 7009).\n- Validate the URI format to prevent misconfiguration.\n- Document any additional headers or authentication required by the revocation endpoint.\n\n**Examples**\n- https://auth.example.com/oauth2/revoke\n- https://api.service.com/oauth2/token/revoke\n\n**Important notes**\n- The revocation URI is distinct from the authorization and token endpoints.\n- Proper implementation of token revocation enhances security by allowing clients to invalidate tokens when no longer needed.\n- Failure to provide a valid revocation URI may prevent clients from properly revoking tokens.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 authorization server configuration.\n- Related to the OAuth 2.0 token endpoint and authorization endpoint.\n- Used in conjunction with client credentials and tokens issued by the authorization server.\n\n**Technical details**\n- Typically accessed via HTTP POST with parameters such as token and token_type_hint.\n- Must handle authentication of the client making the revocation request.\n- Should return appropriate HTTP status codes indicating success or failure of revocation."},"body":{"type":"string","description":"The request body containing the parameters required to revoke an OAuth 2.0 token. This typically includes the token to be revoked and may also specify the token type hint to indicate whether the token is an access token or a refresh token. The body must be formatted according to the application/x-www-form-urlencoded MIME type as per the OAuth 2.0 Token Revocation specification (RFC 7009).\n\n**Field behavior**\n- Contains key-value pairs representing the token and optional token type hint.\n- Must be included in the HTTP POST request to the token revocation endpoint.\n- Parameters are URL-encoded in the request body.\n- Used to instruct the authorization server to invalidate a specific token.\n\n**Implementation guidance**\n- Ensure the body includes the \"token\" parameter with the token string to revoke.\n- Optionally include \"token_type_hint\" with values like \"access_token\" or \"refresh_token\" to assist the server.\n- Use application/x-www-form-urlencoded content type for the request.\n- Validate that the token parameter is present and correctly formatted before sending.\n- Handle server responses to confirm successful revocation or errors.\n\n**Examples**\n- token=SlAV32hkKG\n- token=34xkj23j4k23&token_type_hint=refresh_token\n- token=abcdef123456&token_type_hint=access_token\n\n**Important notes**\n- The token parameter is mandatory; omission will result in an error.\n- The token_type_hint is optional but recommended to improve server processing.\n- Revocation requests must be authenticated as per the authorization server’s requirements.\n- Revoking a token invalidates it immediately, preventing further use.\n- The body must not contain any additional parameters beyond those defined by the specification.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 token revocation endpoint being correctly configured.\n- Requires the client to have a valid token to revoke.\n- May depend on client authentication credentials included in the request headers.\n- The server’s response depends on the correctness of the body parameters.\n\n**Technical details**\n- Content-Type: application/x-www-form-urlencoded\n- Encoding: URL-encoded key-value pairs\n- Parameters:\n - token (string, required): The token to be revoked.\n - token_type_hint (string, optional): A hint about the type of the token.\n- HTTP Method: POST\n- Conforms to RFC 7009 (OAuth 2.0 Token Revocation)"},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the token revocation request for OAuth 2.0. These headers can be used to specify additional metadata such as content type, authorization credentials, custom client information, or any other required HTTP headers that the revocation endpoint expects. This allows for greater flexibility and control over the HTTP request sent to the authorization server when revoking tokens.\n\n**Field behavior**\n- Accepts key-value pairs representing HTTP header names and their corresponding values.\n- Headers are included in the HTTP request sent to the token revocation endpoint.\n- Can override default headers or add custom headers as needed.\n- Supports standard headers like `Authorization`, `Content-Type`, and custom headers.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized and conform to HTTP standards.\n- Avoid including sensitive information in headers unless required and secure.\n- Validate header values to prevent injection or formatting errors.\n- Use this field to comply with specific OAuth 2.0 server requirements for token revocation.\n\n**Examples**\n- `Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0`\n- `Content-Type: application/x-www-form-urlencoded`\n- `X-Custom-Header: customValue`\n\n**Important notes**\n- Headers specified here will be sent only during the token revocation request.\n- Misconfigured headers may cause the revocation request to fail.\n- This field does not affect other OAuth 2.0 requests such as token acquisition or introspection.\n\n**Dependency chain**\n- Used in conjunction with the `oauth2.revoke.url` property specifying the revocation endpoint.\n- May depend on `oauth2.revoke.method` to determine the HTTP method used.\n- Works alongside other OAuth 2.0 configuration properties to complete the revocation flow.\n\n**Technical details**\n- Represented as a map or dictionary of string key-value pairs.\n- Incorporated into the HTTP request headers when making the revocation call.\n- Must comply with HTTP header syntax and encoding rules.\n- Typically used in HTTP POST requests to the revocation endpoint."}},"description":"Indicates whether the OAuth2 token revocation endpoint is supported/enabled (RFC 7009).\n\n**Examples**\n- `true`\n- `false`"},"username":{"type":"string","description":"The username used to authenticate the user within the OAuth2 authorization framework. This value typically represents the unique identifier assigned to the user by the authentication provider or system. It is required when performing resource owner password credentials grant or other flows that involve direct user authentication.\n\n**Field behavior**\n- Must be a non-empty string representing the user's login identifier.\n- Used in conjunction with the password to obtain an access token.\n- Should be case-sensitive depending on the authentication system.\n- Validated against the authentication provider's user database.\n\n**Implementation guidance**\n- Ensure the username is securely transmitted over HTTPS to protect user credentials.\n- Validate the format and existence of the username before processing authentication.\n- Avoid logging the username in plain text to maintain user privacy.\n- Support international characters if the authentication system allows.\n\n**Examples**\n- \"johndoe\"\n- \"user@example.com\"\n- \"alice123\"\n\n**Important notes**\n- The username must correspond to a valid user account in the OAuth2 provider.\n- Incorrect usernames will result in authentication failure.\n- Should be handled securely to prevent exposure of sensitive user information.\n\n**Dependency chain**\n- Typically used alongside the `password` property in OAuth2 password grant flows.\n- Dependent on the OAuth2 server's user management and authentication mechanisms.\n\n**Technical details**\n- Data type: string\n- Maximum length may vary depending on the OAuth2 provider.\n- Should be URL-encoded if included in query parameters or request bodies."},"password":{"type":"string","description":"The OAuth2 **password** value (used with the password grant).\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores the password encrypted at rest (for example as `password_crypt`/`password_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a password is already set.\n\n**Implementation guidance**\n- Provide the plain password value here to set/update it.\n- To keep the existing password unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"unencrypted":{"type":"object","description":"Store all **non-sensitive** fields required by your imports and exports to access the app you are connecting to.\n\nThese values can be referenced by resources within integrator.io through the iClient.\n\n**Examples**\n- `{\"email\":\"my_email@company.com\", \"accountId\": \"8675301\", \"role\":\"admin\"}`\n\n**Important notes**\n- Only store non-sensitive values here (safe to store unencrypted).\n- Use `encrypted` for secrets (passwords, tokens, keys)."},"encrypted":{"type":"object","description":"Store all **sensitive** fields required by your imports and exports to access the app you are connecting to.\n\nThese values are stored with **AES-256 encryption** and other layers of protection to keep your data safe.\nThese values can be referenced by resources within integrator.io through the iClient.\n\n**Examples**\n- `{\"password\":\"celigorocks\"}`\n- `{\"token\":\"x7if4nkovhgr63ghp\"}`\n\n**Important notes**\n- Use this for secrets (passwords, tokens, keys).\n- Values may be masked (e.g., `\"******\"`) in API responses once stored."}},"description":"Configuration settings for OAuth 2.0 authentication, enabling secure authorization and access delegation for API clients. This property typically includes details such as authorization URLs, token URLs, scopes, client credentials, and grant types supported by the OAuth 2.0 provider.\n\n**Field behavior**\n- Defines the OAuth 2.0 flow and parameters required for client authentication.\n- Specifies the endpoints for obtaining authorization and access tokens.\n- Lists the scopes that determine the level of access granted.\n- Supports multiple OAuth 2.0 grant types (e.g., authorization code, client credentials).\n- Enables secure token exchange and refresh mechanisms.\n\n**Implementation guidance**\n- Ensure URLs for authorization and token endpoints are accurate and reachable.\n- Clearly define the scopes to limit access according to least privilege principles.\n- Include client ID and client secret securely, avoiding exposure in client-side code.\n- Support refresh tokens if long-lived sessions are required.\n- Validate tokens on the server side to maintain security.\n\n**Examples**\n- Authorization code flow with authorization URL, token URL, and scopes.\n- Client credentials flow with token URL and client credentials.\n- Implicit flow configuration for single-page applications.\n- Refresh token configuration for renewing access tokens.\n\n**Important notes**\n- OAuth 2.0 configurations must comply with the security best practices to prevent token leakage.\n- Sensitive information such as client secrets should never be exposed publicly.\n- The choice of grant type depends on the client application type and security requirements.\n- Proper error handling should be implemented for token acquisition failures.\n\n**Dependency chain**\n- Depends on the presence of an OAuth 2.0 compliant authorization server.\n- Requires secure storage and transmission of client credentials.\n- Interacts with API endpoints that enforce OAuth 2.0 token validation.\n\n**Technical details**\n- Typically includes fields like authorizationUrl, tokenUrl, refreshUrl, scopes, clientId, clientSecret, and grantTypes.\n- Uses HTTPS endpoints to ensure secure communication.\n- May support PKCE (Proof Key for Code Exchange) for enhanced security in public clients.\n- Tokens are usually JWTs or opaque tokens depending on the OAuth provider implementation."},"salesforce":{"type":"object","properties":{"clientId":{"type":"string","description":"The unique identifier assigned to a client application by Salesforce during the OAuth client registration process. This ID is used to authenticate the client when making API requests and establishing a secure connection with Salesforce services. It is essential for enabling authorized access to Salesforce resources on behalf of the client application.\n**Field behavior**\n- Must be a non-empty string.\n- Used as part of the OAuth authentication flow.\n- Typically remains constant for a given client application.\n- Required for initiating API calls to Salesforce.\n**Implementation guidance**\n- Obtain this value from the Salesforce connected app configuration.\n- Store securely and avoid exposing it in client-side code.\n- Validate the format to ensure it matches Salesforce client ID patterns.\n- Use in conjunction with clientSecret for authentication.\n**Examples**\n- \"3MVG9d6T2QxX9z5l7Y8P0qR1sT2uVwXyZAbCdEfGhIjKlMnOpQrStUvWxYz123456\"\n- \"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\"\n**Important notes**\n- The clientId alone does not grant access; it must be paired with appropriate credentials and tokens.\n- Changing the clientId requires updating all integrations using it.\n- Keep the clientId confidential to prevent unauthorized access.\n**Dependency chain**\n- Dependent on the Salesforce connected app setup.\n- Works alongside clientSecret, redirectUri, and OAuth tokens.\n- Required for generating access tokens.\n**Technical details**\n- Typically a 40-character alphanumeric string.\n- Assigned by Salesforce upon connected app creation.\n- Used in HTTP headers or request parameters during OAuth flows."},"clientSecret":{"type":"string","description":"The Salesforce OAuth **client secret** value.\n\nThis is the value you provide to configure or update the Salesforce iClient. Internally, integrator.io stores this secret encrypted at rest (for example as `clientSecret_crypt` and `clientSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a secret is already set.\n\n**Implementation guidance**\n- Provide the plain client secret value here to set/update it.\n- To keep the existing secret unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"apiToken":{"type":"string","description":"The API token used to authenticate requests to the Salesforce API. This token acts as a secure credential that grants access to Salesforce resources and operations, ensuring that only authorized clients can interact with the Salesforce environment. It is typically generated within Salesforce or through an OAuth flow and must be kept confidential to prevent unauthorized access.\n\n**Field behavior**\n- Used for authenticating API calls to Salesforce.\n- Must be included in the authorization header or as specified by the Salesforce API.\n- Typically has an expiration time and may require periodic renewal.\n- Invalid or expired tokens will result in authentication errors.\n\n**Implementation guidance**\n- Store the token securely, such as in environment variables or secure vaults.\n- Avoid hardcoding the token in source code or exposing it in logs.\n- Implement token refresh logic if using OAuth tokens with limited lifespans.\n- Validate the token format before use to prevent malformed requests.\n\n**Examples**\n- A long alphanumeric string like \"00Dxx0000001gPFEAY!AQ0AQJ...\"\n- OAuth access tokens obtained via Salesforce OAuth 2.0 flows.\n- Tokens generated from Salesforce connected apps for API access.\n\n**Important notes**\n- The API token is sensitive information and should be treated like a password.\n- Sharing or leaking the token can compromise Salesforce data security.\n- Ensure compliance with Salesforce security policies when handling tokens.\n- Different Salesforce environments (non-production vs production) may require different tokens.\n\n**Dependency chain**\n- Dependent on Salesforce user credentials or OAuth authorization flows.\n- Used in conjunction with the Salesforce instance URL and API endpoints.\n- May require additional headers or parameters as per Salesforce API specifications.\n\n**Technical details**\n- Typically included in HTTP headers as \"Authorization: Bearer {apiToken}\".\n- May have scopes or permissions associated depending on how it was generated.\n- Tokens may be JWTs or opaque strings depending on the authentication method.\n- Salesforce APIs validate the token on each request to authorize access."},"privateKey":{"type":"string","description":"The Salesforce private key value used for authentication flows such as JWT bearer token OAuth.\n\nThis is the value you provide to configure or update the Salesforce iClient. Internally, integrator.io stores this key encrypted at rest (for example as `privateKey_crypt`/`privateKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a key is already set.\n\n**Implementation guidance**\n- Provide the plaintext private key value here to set/update it (often PEM formatted).\n- To keep the existing private key unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"publicKey":{"type":"string","description":"The publicKey property represents the public cryptographic key used for secure data encryption, verification, or authentication processes within the Salesforce integration. This key is typically part of a public-private key pair and is used to encrypt data or verify digital signatures without exposing the private key. It ensures secure communication and data integrity between systems.\n\n**Field behavior**\n- Accepts a string value representing the public key in a standard format (e.g., PEM, DER).\n- Used to encrypt data or verify signatures in cryptographic operations.\n- Must be provided in a format compatible with the consuming system.\n- Immutable once set for a given integration instance to maintain security.\n\n**Implementation guidance**\n- Ensure the public key is generated using a secure and recognized cryptographic algorithm (e.g., RSA, ECDSA).\n- Validate the key format before accepting it to prevent errors during cryptographic operations.\n- Store the key securely and restrict access to prevent unauthorized modifications.\n- Update the key only through a controlled process to avoid breaking integrations.\n\n**Examples**\n- A PEM-encoded RSA public key string starting with \"-----BEGIN PUBLIC KEY-----\".\n- An ECDSA public key represented in base64 encoding.\n- A public key string used to verify JWT tokens issued by Salesforce.\n\n**Important notes**\n- The publicKey must correspond to the private key held securely by the entity performing signing or decryption.\n- Do not expose the private key in any API or configuration.\n- Incorrect or malformed keys will cause authentication or encryption failures.\n- Keep the key updated in case of key rotation policies.\n\n**Dependency chain**\n- Dependent on the cryptographic algorithm and key pair generation process.\n- Used by authentication, encryption, or signature verification components.\n- May be linked to other security configurations such as certificates or token validation settings.\n\n**Technical details**\n- Typically encoded in PEM or DER format.\n- May include metadata such as key type and length.\n- Should comply with relevant security standards (e.g., PKCS#1, X.509).\n- Size and algorithm choice affect security strength and performance."}},"description":"Configuration settings and credentials required to integrate with Salesforce, enabling seamless data synchronization and interaction with Salesforce APIs. This property typically includes authentication details, API endpoints, and any necessary parameters for establishing a secure connection to a Salesforce instance.\n\n**Field behavior**\n- Holds all necessary information to authenticate and communicate with Salesforce services.\n- Used to configure API calls for data retrieval, updates, and other Salesforce operations.\n- May include nested objects or fields such as client ID, client secret, access tokens, instance URLs, and API versions.\n\n**Implementation guidance**\n- Ensure sensitive information like client secrets and access tokens are securely stored and transmitted.\n- Validate the presence and correctness of required fields before attempting Salesforce integration.\n- Support token refresh mechanisms if applicable to maintain session validity.\n- Allow configuration flexibility to support different Salesforce environments (e.g., non-production, production).\n\n**Examples**\n- An object containing OAuth credentials: client_id, client_secret, refresh_token, and instance_url.\n- Configuration specifying API version and endpoint URLs.\n- JSON structure with nested authentication and connection parameters.\n\n**Important notes**\n- Proper error handling should be implemented for authentication failures or API call errors.\n- Salesforce API limits and quotas should be considered when designing integration logic.\n- Secure handling of credentials is critical to prevent unauthorized access.\n- The structure and required fields may vary depending on the Salesforce API version and authentication method used.\n\n**Dependency chain**\n- Dependent on Salesforce authentication mechanisms (OAuth 2.0, username-password flow, etc.).\n- Relies on network connectivity to Salesforce endpoints.\n- May depend on external libraries or SDKs for Salesforce API interaction.\n\n**Technical details**\n- Typically involves OAuth 2.0 tokens or username-password credentials.\n- Uses HTTPS for secure communication with Salesforce REST or SOAP APIs.\n- May include refresh token logic to maintain long-term access.\n- Supports configuration of API versioning to align with Salesforce API changes."},"ebay":{"type":"object","properties":{"appId":{"type":"string","description":"The unique identifier assigned to an application registered with the eBay developer program. This ID is used to authenticate API requests and associate them with a specific application.\n\n**Field behavior**\n- Must be included in API requests to identify the calling application.\n- Typically a string consisting of alphanumeric characters.\n- Used to track usage and enforce rate limits for the application.\n- Required for accessing most eBay APIs.\n\n**Implementation guidance**\n- Obtain the appId by registering your application on the eBay Developer Program portal.\n- Keep the appId confidential to prevent unauthorized use.\n- Include the appId in the request headers or parameters as specified by the API documentation.\n- Validate the appId format before sending requests to avoid errors.\n\n**Examples**\n- \"12345678-1234-1234-1234-123456789abc\"\n- \"MyEbayAppID2024\"\n- \"APP-9876543210\"\n\n**Important notes**\n- The appId is different from other eBay credentials such as client ID or client secret.\n- Using an invalid or expired appId will result in authentication errors.\n- Do not share your appId publicly to protect your application's security.\n\n**Dependency chain**\n- Depends on successful registration with the eBay Developer Program.\n- Used in conjunction with other authentication credentials like OAuth tokens.\n- Required before making authorized API calls.\n\n**Technical details**\n- Typically a UUID or a unique string assigned by eBay.\n- Passed as part of HTTP headers or query parameters depending on the API.\n- Used by eBay servers to identify and authenticate the application making the request."},"devId":{"type":"string","description":"The unique identifier assigned to a developer or development team by eBay. This ID is used to authenticate and track API usage associated with the developer's applications. It ensures that API requests are properly attributed and helps manage access permissions and rate limits.\n\n**Field behavior**\n- Must be included in API requests requiring developer authentication.\n- Used to identify the source of API calls.\n- Typically remains constant for a given developer or development team.\n- Should be kept confidential to prevent unauthorized use.\n\n**Implementation guidance**\n- Obtain the devId by registering as a developer on the eBay Developer Program portal.\n- Include the devId in all relevant API request headers or parameters as specified by eBay.\n- Store the devId securely in your application environment.\n- Do not expose the devId in client-side code or public repositories.\n\n**Examples**\n- \"1234567890\"\n- \"dev_abcdef123456\"\n- \"9876543210\"\n\n**Important notes**\n- The devId is distinct from other eBay identifiers such as appId, certId, or auth tokens.\n- Misuse or leakage of the devId can lead to unauthorized API access.\n- Changes to the devId require updating all applications using it.\n- Ensure compliance with eBay's developer policies when using the devId.\n\n**Dependency chain**\n- Often used alongside appId and certId for full API authentication.\n- May be required before obtaining OAuth tokens or other credentials.\n- Linked to developer account settings and permissions on eBay.\n\n**Technical details**\n- Typically a string of alphanumeric characters.\n- Assigned by eBay upon developer registration.\n- Used in API request headers or query parameters depending on the API endpoint.\n- Validated by eBay servers to authorize API access."},"certId":{"type":"string","description":"The eBay certificate ID value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `certId_crypt`/`certId_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext certificate ID value here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"ruName":{"type":"string","description":"The Russian name associated with the eBay entity, typically used for localization and display purposes in Russian-language contexts. This field contains the name as it should appear to Russian-speaking users, ensuring proper representation and cultural relevance.\n\n**Field behavior**\n- Represents the localized name in Russian.\n- Used primarily for display in Russian language interfaces.\n- Should accurately reflect the entity's name in Russian script.\n- May be omitted if no Russian localization is available.\n\n**Implementation guidance**\n- Ensure the name is correctly translated and culturally appropriate.\n- Use Cyrillic characters as per Russian language standards.\n- Validate the string for encoding compatibility (UTF-8).\n- Update this field when the entity's Russian name changes.\n\n**Examples**\n- \"Электроника\" (Electronics)\n- \"Мода\" (Fashion)\n- \"Дом и сад\" (Home and Garden)\n\n**Important notes**\n- This field is optional if the entity does not have a Russian localization.\n- Avoid transliterations; use proper Russian language terms.\n- Consistency with other localized names is important for user experience.\n\n**Dependency chain**\n- May depend on the primary name or English name for context.\n- Used in conjunction with other localized name fields for multi-language support.\n\n**Technical details**\n- Data type: string.\n- Character encoding: UTF-8.\n- Maximum length should conform to system constraints for name fields."}},"description":"Contains configuration settings and credentials specific to eBay integration within the application. This property manages parameters required to connect, authenticate, and interact with eBay's APIs and services.\n\n**Field behavior**\n- Holds all necessary eBay-related configuration details.\n- Used to enable and customize eBay platform interactions.\n- May include API keys, tokens, endpoint URLs, and feature toggles.\n- Supports dynamic updates to eBay integration settings without redeploying the application.\n\n**Implementation guidance**\n- Securely store sensitive information such as API credentials.\n- Validate the presence and correctness of required fields before making API calls.\n- Support environment-specific configurations for different environments.\n- Ensure compatibility with the latest eBay API versions.\n- Provide clear error handling and logging for eBay-related operations.\n\n**Examples**\n- API key and secret for eBay developer account.\n- OAuth tokens for user authentication with eBay.\n- URLs for eBay REST or Trading API endpoints.\n- Flags to enable or disable specific eBay features like inventory management or order processing.\n\n**Important notes**\n- Credentials must be kept confidential and never exposed in client-side code.\n- Regularly update tokens and keys to maintain uninterrupted service.\n- Comply with eBay's API usage policies and rate limits.\n- Changes to this configuration may affect live eBay transactions and listings.\n\n**Dependency chain**\n- Dependent on eBay developer account and API access permissions.\n- Interacts with authentication modules to manage tokens.\n- Works alongside order management and inventory systems for synchronization.\n- May depend on network connectivity and proxy settings for API calls.\n\n**Technical details**\n- Typically structured as a nested object containing keys like clientId, clientSecret, accessToken, refreshToken, and apiEndpoints.\n- May include metadata such as token expiration timestamps and scopes.\n- Supports serialization and secure storage mechanisms.\n- Designed to be extensible for future eBay API features and versions."},"amazonmws":{"type":"object","properties":{"accessKeyId":{"type":"string","description":"The Access Key ID is a unique identifier assigned to your Amazon MWS (Marketplace Web Service) account, used to authenticate API requests. It acts as a public credential that, together with the Secret Access Key, allows secure access to Amazon MWS services. This key is essential for programmatic interaction with Amazon's seller APIs, enabling operations such as order retrieval, inventory management, and report generation.\n\n**Field behavior**\n- Must be a valid, active Access Key ID issued by Amazon.\n- Used in conjunction with the Secret Access Key to sign API requests.\n- Should be kept confidential to prevent unauthorized access.\n- Typically a 20-character alphanumeric string.\n\n**Implementation guidance**\n- Retrieve the Access Key ID from your AWS Management Console or Amazon MWS developer account.\n- Ensure the Access Key ID corresponds to the correct AWS user with appropriate permissions.\n- Do not hard-code the key in publicly accessible code repositories.\n- Rotate keys periodically to maintain security best practices.\n\n**Examples**\n- \"AKIAIOSFODNN7EXAMPLE\"\n- \"ABCD1234EFGH5678IJKL\"\n- \"A1B2C3D4E5F6G7H8I9J0\"\n\n**Important notes**\n- The Access Key ID alone is insufficient for authentication; it must be paired with the Secret Access Key.\n- Exposure of the Access Key ID and Secret Access Key can lead to unauthorized access and potential data breaches.\n- If compromised, immediately revoke and regenerate the keys via the AWS console.\n- Access Key IDs are case-sensitive.\n\n**Dependency chain**\n- Requires a corresponding Secret Access Key for request signing.\n- Must be associated with an AWS IAM user or role with Amazon MWS permissions.\n- Used alongside other credentials such as Seller ID and MWS Auth Token for full API access.\n\n**Technical details**\n- Format: 20-character alphanumeric string.\n- Used in the AWS Signature Version 2 or 4 signing process.\n- Included in the HTTP headers or query parameters of API requests.\n- Validated by Amazon MWS servers to authorize API calls."},"secretKey":{"type":"string","description":"The Amazon MWS secret key value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `secretKey_crypt`/`secretKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext secret key value here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."}},"description":"Configuration settings required to integrate with the Amazon Marketplace Web Service (Amazon MWS) API, enabling programmatic access to Amazon seller account data and operations. This includes credentials and parameters necessary for authentication, authorization, and interaction with various Amazon MWS endpoints.\n\n**Field behavior**\n- Contains all necessary authentication credentials such as Access Key ID, Secret Access Key, Seller ID, and MWS Auth Token.\n- May include configuration options like marketplace IDs, region settings, and API version.\n- Used to establish secure and authorized communication with Amazon MWS services.\n- Typically required for operations such as order retrieval, inventory management, and report generation.\n\n**Implementation guidance**\n- Ensure all credentials are stored securely and transmitted over encrypted channels.\n- Validate the presence and correctness of all required fields before attempting API calls.\n- Support refreshing or updating credentials as needed to maintain uninterrupted access.\n- Handle error responses gracefully, including authentication failures or permission issues.\n- Follow Amazon MWS best practices and rate limits to avoid throttling.\n\n**Examples**\n- Access Key ID: \"AKIAIOSFODNN7EXAMPLE\"\n- Secret Access Key: \"1234567890abcdef1234567890abcdef12345678\"\n- Seller ID: \"A1XEXAMPLE123\"\n- MWS Auth Token: \"amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE\"\n\n**Important notes**\n- Amazon MWS is being succeeded by the Selling Partner API (SP-API); consider migration plans.\n- Credentials must be kept confidential to prevent unauthorized access.\n- API access is subject to Amazon’s terms of service and usage policies.\n- Proper error handling is critical to manage API rate limits and service disruptions.\n\n**Dependency chain**\n- Requires valid Amazon seller account with MWS access enabled.\n- Dependent on network connectivity to Amazon MWS endpoints.\n- May depend on other configuration properties such as marketplace identifiers.\n\n**Technical details**\n- Uses RESTful API calls with XML or JSON payloads.\n- Authentication is based on AWS Signature Version 2 or 4.\n- Supports multiple API sections including Orders, Reports, Feeds, and Products.\n- Requires timestamp synchronization to prevent request rejection."},"jwt":{"type":"object","description":"A JSON Web Token (JWT) used for securely transmitting information between parties as a JSON object. This token is typically used for authentication and authorization purposes, ensuring that the client has valid credentials to access protected resources. The JWT contains encoded header, payload, and signature sections that verify the token's integrity and authenticity.\n**Field behavior**\n- Must be a valid JWT string following the standard format: header.payload.signature.\n- Used to authenticate API requests and authorize access to specific endpoints.\n- Typically included in the Authorization header as a Bearer token.\n- Should have an expiration time to enhance security.\n**Implementation guidance**\n- Validate the JWT on the server side to ensure it is properly signed and not expired.\n- Use secure algorithms (e.g., RS256 or HS256) for signing the token.\n- Store sensitive information in the payload with caution, as JWTs can be decoded by clients.\n- Refresh tokens should be used to obtain new JWTs when the current one expires.\n**Examples**\n- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\n- eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJleGFtcGxlLmNvbSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJleHAiOjE2MjQ2MjQwMDB9.DQABCD1234abcd5678efgh9012ijkl3456mnop7890qrstuv\n**Important notes**\n- JWTs should be transmitted over secure channels (HTTPS) to prevent interception.\n- Do not store JWTs in insecure storage locations on the client side (e.g., localStorage) to avoid XSS attacks.\n- Always verify the token's signature and claims before granting access.\n- Be aware of token expiration and implement proper handling for expired tokens.\n**Dependency chain**\n- Depends on the authentication mechanism generating the JWT.\n- Requires a"}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/iClients":{"get":{"summary":"List iClients","description":"Returns a list of all iClients configured in the account.\n\n**Path casing:** the API is case-insensitive — `/v1/iClients`, `/v1/iclients`,\nand `/v1/ICLIENTS` all resolve to the same endpoint.\n\n**Pagination:** this endpoint does **not** paginate. All iClients are returned\nin a single response with no `Link` header.\n","operationId":"listIClients","tags":["iClients"],"responses":{"200":{"description":"Successfully retrieved list of iClients (may be an empty array)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Response"}}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}} ``` ## Create an iClient > Creates a new iClient configuration.
```json {"openapi":"3.1.0","info":{"title":"iClients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Configuration for iclient","required":["provider"],"properties":{"_httpConnectorId":{"type":"string","format":"objectId","description":"Specifies the unique identifier for the HTTP connector used to establish network communication. This ID links the configuration to a specific HTTP connector instance, enabling the system to route requests appropriately.\n\n**Field behavior**\n- Accepts a string representing the connector's unique ID.\n- Used to reference an existing HTTP connector configuration.\n- Required when the operation depends on a specific HTTP connector.\n- Immutable once set during the lifecycle of the configuration.\n\n**Implementation guidance**\n- Ensure the ID corresponds to a valid and active HTTP connector within the system.\n- Validate the format of the ID to match expected patterns (e.g., UUID or predefined naming conventions).\n- Use this field to dynamically select or switch HTTP connectors in multi-connector environments.\n- Handle cases where the specified connector ID does not exist or is unavailable.\n\n**Examples**\n- \"connector-1234abcd\"\n- \"http-conn-5678efgh\"\n- \"uuid-550e8400-e29b-41d4-a716-446655440000\"\n\n**Important notes**\n- This field is critical for routing HTTP requests correctly.\n- Incorrect or missing connector IDs may lead to failed connections or errors.\n- The connector ID must be managed securely to prevent unauthorized access.\n\n**Dependency chain**\n- Depends on the existence of HTTP connector configurations within the system.\n- May influence or be influenced by authentication, proxy, or network settings tied to the connector.\n\n**Technical details**\n- Typically stored as a string data type.\n- May be used as a key in lookup tables or configuration maps.\n- Should be indexed for efficient retrieval in large-scale systems."},"_httpConnectorApiId":{"type":"string","format":"objectId","description":"Specifies the unique identifier of the HTTP Connector API associated with the current configuration or operation. This ID is used to reference and link the HTTP Connector API within the system, enabling seamless integration and communication between components.\n\n**Field behavior**\n- Acts as a reference pointer to a specific HTTP Connector API instance.\n- Must be a valid and existing API identifier within the system.\n- Used to establish connections and route requests appropriately.\n- Typically immutable once set to ensure consistent API linkage.\n\n**Implementation guidance**\n- Validate the ID against the list of available HTTP Connector APIs before assignment.\n- Ensure the ID format complies with the system’s identifier standards (e.g., UUID or specific naming conventions).\n- Handle cases where the referenced API ID does not exist or is deprecated.\n- Use this property to dynamically bind or switch HTTP Connector APIs in configurations.\n\n**Examples**\n- \"api-123e4567-e89b-12d3-a456-426614174000\"\n- \"http-connector-v2\"\n- \"connectorApi_987654321\"\n\n**Important notes**\n- This property is critical for routing HTTP requests correctly.\n- Incorrect or missing IDs can lead to failed API calls or misrouted traffic.\n- Changes to this ID should be managed carefully to avoid breaking integrations.\n- May require appropriate permissions to read or modify.\n\n**Dependency chain**\n- Depends on the existence of the HTTP Connector API registry or catalog.\n- Used by components responsible for HTTP request handling and routing.\n- May influence authentication, authorization, and logging mechanisms tied to the API.\n\n**Technical details**\n- Typically stored as a string data type.\n- Should be indexed for efficient lookup in large systems.\n- May be linked to metadata describing the HTTP Connector API’s capabilities and endpoints.\n- Often integrated with API management tools or service registries."},"enableIClientReferences":{"type":"boolean","description":"Determines whether the system should enable support for iClient references, allowing integration and interaction with iClient components or services. This setting controls the activation of features that facilitate communication, data exchange, or functionality extension through iClient references.\n\n**Field behavior**\n- When set to true, iClient references are enabled, allowing the system to recognize and process iClient-related interactions.\n- When set to false, iClient references are disabled, and any related functionality will be ignored or unavailable.\n- The field typically accepts a boolean value.\n\n**Implementation guidance**\n- Enable this setting only if your application requires integration with iClient components.\n- Ensure that enabling this does not conflict with other system configurations or security policies.\n- Validate the impact on performance and compatibility when toggling this setting.\n\n**Examples**\n- true: Enables iClient references, allowing the system to interact with iClient services.\n- false: Disables iClient references, preventing any iClient-related processing.\n\n**Important notes**\n- Enabling iClient references may require additional permissions or configurations on the client or server side.\n- Disabling this feature can improve security by limiting external references but may reduce functionality.\n- Changes to this setting might require a system restart or reinitialization to take effect.\n\n**Dependency chain**\n- May depend on the presence of iClient libraries or modules within the system.\n- Could be linked to authentication or authorization settings related to client references.\n- Might interact with other integration or communication-related configuration properties.\n\n**Technical details**\n- Typically implemented as a boolean flag in the configuration.\n- Controls conditional logic paths that handle iClient reference processing.\n- May influence API endpoints, middleware behavior, or client-server communication protocols."},"formType":{"type":"string","enum":["assistant","http"],"description":"Specifies which UI form is used to configure this iClient in integrator.io.\n\n**Critical:** How this is determined in the UI\n- If `_httpConnectorId` is set, the UI uses the **assistant** form.\n- If `_httpConnectorId` is not set, the UI uses the **http** form.\n\nThe **assistant** form is used for applications where integrator.io provides a guided setup assistant to make configuration easier.\n\n**Field behavior**\n- Controls the form layout and fields displayed in the UI.\n- May affect validation and conditional rendering in the UI.\n- Must be one of: `assistant`, `http`.\n\n**Implementation guidance**\n- Prefer letting the UI default this value based on `_httpConnectorId` unless you have a specific reason to override it.\n- Use `assistant` when configuring via an iClient assistant-backed application.\n- Use `http` for the standard HTTP configuration form.\n\n**Examples**\n- `assistant`\n- `http`\n\n**Important notes**\n- The value must be lowercase (`assistant` or `http`).\n- Changing this value impacts the UI experience for configuring the iClient.\n\n**Dependency chain**\n- Depends on whether the iClient is tied to an HTTP Connector (`_httpConnectorId`).\n- Influences which UI renderer is selected for the resource.\n\n**Technical details**\n- Stored as a lowercase string enum."},"settings":{"type":"object","description":"An object containing configuration options that customize the behavior and features of the system or application. This property allows users or developers to specify various parameters, preferences, and toggles that influence how the system operates, enabling flexible and dynamic adjustments to meet different requirements.\n\n**Field behavior**\n- Accepts a structured set of key-value pairs representing different configuration settings.\n- Can include nested objects to group related settings logically.\n- Modifications to this property typically affect system behavior immediately or upon the next initialization.\n- Supports enabling or disabling features, setting thresholds, defining modes, and other customizable options.\n\n**Implementation guidance**\n- Validate the structure and data types of the settings to ensure correctness.\n- Provide default values for unspecified settings to maintain predictable behavior.\n- Allow extensibility to accommodate future settings without breaking compatibility.\n- Document each configurable option clearly to guide users in setting appropriate values.\n\n**Examples**\n- Setting a timeout duration with `\"timeout\": 3000`.\n- Configuring logging levels with `\"logging\": {\"level\": \"verbose\", \"output\": \"file\"}`.\n- Toggling feature flags such as `\"features\": {\"betaAccess\": true, \"newUI\": false}`.\n\n**Important notes**\n- Changes to settings may require system restart or reinitialization to take effect.\n- Improper configuration can lead to unexpected behavior or degraded performance.\n- Sensitive settings should be protected and validated to prevent security risks.\n- The settings object should be kept as concise as possible to avoid complexity.\n\n**Dependency chain**\n- Dependent on the system's configuration management module.\n- May influence or be influenced by user preferences and environment variables.\n- Interacts with feature toggles, access controls, and runtime parameters.\n\n**Technical details**\n- Typically represented as a JSON object or equivalent data structure.\n- Supports various data types including strings, numbers, booleans, arrays, and nested objects.\n- May be stored in configuration files, databases, or managed via APIs.\n- Should support serialization and deserialization for persistence and transmission."},"settingsForm":{"type":"object","description":"An object representing the configuration and structure of a settings form used to capture user preferences or application parameters. This form typically includes fields, validation rules, default values, and UI metadata necessary for rendering and processing the settings interface.\n\n**Field behavior**\n- Defines the layout and components of the settings form.\n- Contains input fields with associated validation and default values.\n- Supports dynamic updates based on user interaction or external data.\n- Facilitates submission and retrieval of user-configured settings.\n\n**Implementation guidance**\n- Structure the form object to include field definitions, types, labels, and validation constraints.\n- Include metadata for UI rendering such as placeholders, tooltips, and grouping.\n- Ensure validation rules are comprehensive to prevent invalid input.\n- Support extensibility to add or modify fields without breaking existing functionality.\n\n**Examples**\n- A form object with fields for username, email preferences, and notification settings.\n- A nested form structure with sections for privacy, display, and account management.\n- Validation rules specifying required fields and acceptable value ranges.\n\n**Important notes**\n- The form should be designed to accommodate localization and accessibility standards.\n- Changes to the form structure may require corresponding updates in the UI and backend processing.\n- Ensure sensitive data fields are handled securely and comply with privacy regulations.\n\n**Dependency chain**\n- Depends on UI components to render the form fields.\n- Relies on validation logic to enforce input correctness.\n- Interacts with backend services to save and retrieve settings data.\n\n**Technical details**\n- Typically represented as a JSON object or similar structured data format.\n- May include nested objects or arrays to represent complex form hierarchies.\n- Validation rules can be expressed using standard schemas or custom logic.\n- Supports integration with form libraries or frameworks for rendering and state management."},"provider":{"type":"string","enum":["google","salesforce","azureoauth","windowslive","shopify","integrator","zendesk","bigcommerce","netsuite","ebay","ebay-xml","asana","box","dropbox","clover","servicenow","jobvite","twilio","certify","dropbox","squareup","docusign","woocommerce","microsoftbusinesscentral","custom_oauth2","amazonmws"],"description":"Specifies the **authentication provider/method** used by this iClient.\n\nThis value determines which authentication flow and credential fields are used (e.g., Google OAuth, Salesforce OAuth, NetSuite token-based auth, or a custom OAuth2 provider).\n\n**Field behavior**\n- Required.\n- Must be one of the supported provider enum values.\n- Drives the UI and validation rules for which authentication settings are shown/required.\n\n**Implementation guidance**\n- Pick the provider that matches the system you are authenticating against.\n- For generic OAuth2 providers, use `custom_oauth2`.\n- Ensure the corresponding auth configuration under `oauth2`, `jwt`, or provider-specific sections is populated as needed.\n\n**Examples**\n- google\n- salesforce\n- netsuite\n- custom_oauth2\n\n**Important notes**\n- This is not a human/vendor label — it is the provider key that selects an authentication method.\n\n**Dependency chain**\n- Influences which auth sub-configurations are applicable (for example, `oauth2.*`, `netsuite.*`, `salesforce.*`, `jwt.*`).\n\n**Technical details**\n- Stored as a lowercase string enum (see the `enum` list for allowed values)."},"name":{"type":"string"},"published":{"type":"boolean","description":"Indicates whether this iClient is published (available/visible for use).\n\n**Field behavior**\n- Boolean flag: `true` or `false`.\n- Used to control publication status in the UI.\n\n**Implementation guidance**\n- Default to `false` unless you intend to publish the iClient.\n\n**Examples**\n- `true`\n- `false`"},"enableJWT":{"type":"boolean","description":"Enables use of an additional **JWT assertion** as part of an OAuth authentication flow.\n\nUse this field when the OAuth provider requires a JWT assertion as a component of the OAuth specification. When enabled, you can use the Handlebars path `{{{iClient.jwt.token}}}` to obtain the JWT token value, which is then used in the **request body of the token URL** to generate an access token.\n\n**Field behavior**\n- When `true`, the iClient includes a JWT assertion/token as part of the OAuth token request.\n- When `false`, the OAuth flow does not incorporate a JWT assertion component.\n\n**Implementation guidance**\n- Enable only when your OAuth provider requires JWT assertion.\n- Populate the `jwt` configuration (e.g., `iClient.jwt.*`) so `{{{iClient.jwt.token}}}` can be resolved.\n- Use the resolved JWT token in the token request body parameters for the OAuth token URL, as required by the provider.\n\n**Examples**\n- `true` (OAuth token request includes a JWT assertion component)\n- `false` (standard OAuth flow without JWT assertion)\n\n**Important notes**\n- This flag is for **OAuth JWT assertion** use-cases; it does not mean “all requests must include a JWT Authorization header.”\n- If enabled without configuring `iClient.jwt`, token generation will fail.\n\n**Dependency chain**\n- Depends on `iClient.jwt` fields and the provider’s OAuth token request requirements.\n- Used when constructing the token URL request body for OAuth.\n\n**Technical details**\n- The JWT token can be referenced via `{{{iClient.jwt.token}}}` during request templating."},"netsuite":{"type":"object","properties":{"consumerKey":{"type":"string","description":"The NetSuite consumer key value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `consumerKey_crypt`/`consumerKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext consumer key here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"consumerSecret":{"type":"string","description":"The NetSuite consumer secret value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `consumerSecret_crypt`/`consumerSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext consumer secret here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."}},"description":"Configuration settings and credentials required to integrate with the NetSuite platform, enabling seamless data synchronization and interaction with NetSuite's ERP and CRM services. This property typically includes authentication details, API endpoints, and any necessary parameters for establishing a secure connection.\n\n**Field behavior**\n- Holds all necessary information to authenticate and communicate with NetSuite APIs.\n- Used to configure integration settings such as account ID, role, and environment.\n- Enables data exchange between the application and NetSuite for operations like record creation, updates, and queries.\n- May support multiple authentication methods, including token-based and OAuth.\n\n**Implementation guidance**\n- Ensure sensitive credentials are stored securely and encrypted.\n- Validate all required fields before attempting connection to NetSuite.\n- Support environment-specific configurations for different environments.\n- Handle error responses gracefully to maintain integration stability.\n- Keep the configuration up to date with NetSuite API version changes.\n\n**Examples**\n- API credentials including consumer key, consumer secret, token ID, and token secret.\n- Account ID and role ID for specifying the NetSuite account and user role.\n- URLs for NetSuite REST or SOAP API endpoints.\n- Flags or settings indicating the target environment.\n\n**Important notes**\n- Incorrect or outdated credentials will prevent successful integration.\n- NetSuite API limits and governance should be considered to avoid throttling.\n- Regularly review and rotate credentials to maintain security.\n- Integration may require specific permissions within NetSuite roles.\n\n**Dependency chain**\n- Dependent on secure storage mechanisms for credentials.\n- Relies on network connectivity to NetSuite services.\n- May depend on other configuration properties like logging or retry policies.\n\n**Technical details**\n- Typically includes OAuth 1.0a or token-based authentication parameters.\n- May require JSON or XML formatted configuration data.\n- Supports both REST and SOAP API protocols depending on use case.\n- Configuration format should align with NetSuite’s API specification requirements."},"oauth2":{"type":"object","properties":{"clientId":{"type":"string","description":"The unique identifier assigned to a client application during the OAuth 2.0 registration process. This client ID is used to identify the application when making authorization requests to the OAuth 2.0 authorization server. It is a public value that is included in authorization requests and token exchanges to associate the requests with the registered client.\n\n**Field behavior**\n- Must be a unique string assigned by the authorization server.\n- Used in authorization and token request flows to identify the client application.\n- Typically remains constant for the lifetime of the client registration.\n- Should be included in all OAuth 2.0 requests where client identification is required.\n\n**Implementation guidance**\n- Obtain the client ID from the OAuth 2.0 provider during client registration.\n- Store the client ID securely within the application configuration.\n- Do not treat the client ID as a secret; it can be exposed in URLs and logs.\n- Validate the client ID format according to the OAuth provider’s specifications.\n\n**Examples**\n- \"abc123xyz\"\n- \"myapp-client-001\"\n- \"1234567890abcdef\"\n\n**Important notes**\n- The client ID is distinct from the client secret; the latter must be kept confidential.\n- Exposure of the client ID does not compromise security but is necessary for proper OAuth flows.\n- Ensure the client ID matches exactly the value registered with the OAuth provider to avoid authentication errors.\n\n**Dependency chain**\n- Dependent on successful client registration with the OAuth 2.0 authorization server.\n- Used in conjunction with client secret (if applicable) during token requests.\n- Required for constructing authorization URLs and token exchange requests.\n\n**Technical details**\n- Typically a string of alphanumeric characters, sometimes including dashes or underscores.\n- May be case-sensitive depending on the OAuth provider.\n- Passed as a query parameter or in the request body during OAuth flows.\n- Must conform to the OAuth 2.0 specification and provider-specific requirements."},"clientSecret":{"type":"string","description":"The OAuth 2.0 **client secret** value.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this secret encrypted at rest (for example as `clientSecret_crypt` and `clientSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a secret is already set.\n\n**Implementation guidance**\n- Provide the plain client secret value here to set/update it.\n- To keep the existing secret unchanged during an update, omit this field (or, if the API/UI returns a masked value, keep `\"******\"` as-is)."},"scope":{"type":"array","items":{"type":"string"},"description":"OAuth 2.0 scopes requested for the access token.\n\n**API behavior:** the API accepts a string on input but always\nreturns an **array of strings** in responses. When you send a\nspace-delimited string like `\"openid profile\"`, the response\nwraps it as `[\"openid profile\"]`.\n\n**Examples**\n- `[]`\n- `[\"openid profile email\"]`\n- `[\"read\", \"write\"]`"},"scopeDelimiter":{"type":"string","description":"Specifies the character or string used to separate multiple OAuth2 scopes within a single authorization request or token. This delimiter enables the parsing and interpretation of scope values when they are provided as a concatenated string. Common delimiters include spaces, commas, or other characters depending on the OAuth2 provider's implementation.\n\n**Field behavior**\n- Defines how multiple scopes are split and recognized in authorization requests.\n- Ensures correct parsing of scope strings when multiple scopes are requested simultaneously.\n- Influences the format of the scope parameter in OAuth2 authorization URLs and tokens.\n\n**Implementation guidance**\n- Choose a delimiter that aligns with the OAuth2 provider's specification or defaults (e.g., space is standard per OAuth2 spec).\n- Ensure consistent use of the delimiter across all OAuth2 requests and responses.\n- Validate scope strings to correctly split and handle multiple scopes using this delimiter.\n- Document the chosen delimiter clearly for developers integrating with the API.\n\n**Examples**\n- Space character (\" \") as a delimiter: \"read write delete\"\n- Comma (\",\") as a delimiter: \"read,write,delete\"\n- Semicolon (\";\") as a delimiter: \"read;write;delete\"\n\n**Important notes**\n- The OAuth2 specification (RFC 6749) recommends using a space character as the scope delimiter.\n- Some OAuth2 providers may use non-standard delimiters; this property allows customization to accommodate those cases.\n- Incorrect delimiter configuration can lead to authorization failures or incorrect scope parsing.\n- When omitted, the default delimiter is typically a space character.\n\n**Dependency chain**\n- Depends on the OAuth2 authorization server's scope formatting requirements.\n- Influences how the 'scope' parameter in authorization requests and tokens is constructed and parsed.\n- May affect downstream components that interpret or validate scopes.\n\n**Technical details**\n- Typically a single character but can be a string if supported.\n- Used in string splitting functions to parse scope lists.\n- Should be URL-encoded if it is a special character in URLs.\n- Must be consistent with the OAuth2 provider's expectations to ensure interoperability."},"redirectUri":{"type":"string","description":"The URI to which the authorization server will redirect the user-agent after granting or denying access. This URI must be registered with the authorization server and should exactly match one of the pre-registered redirect URIs to prevent security vulnerabilities such as open redirect attacks. It is used in OAuth 2.0 authorization flows to receive authorization codes or access tokens securely.\n\n**Field behavior**\n- Specifies the callback endpoint for the authorization response.\n- Must be an absolute URI.\n- Used to return authorization codes or tokens after user consent.\n- Validated against pre-registered URIs to ensure security.\n\n**Implementation guidance**\n- Ensure the redirect URI is registered with the authorization server before use.\n- Use HTTPS to protect the integrity and confidentiality of the redirect.\n- Avoid using wildcard or overly broad redirect URIs.\n- Validate the redirect URI strictly on the server side to prevent open redirect vulnerabilities.\n\n**Examples**\n- https://client.example.com/callback\n- https://app.example.com/oauth2/callback\n- https://localhost:8080/auth/callback (for development purposes)\n\n**Important notes**\n- Mismatched redirect URIs will cause authorization requests to fail.\n- Redirect URIs should not contain fragments (#).\n- Avoid using query parameters unless necessary and registered.\n- The redirect URI is critical for security; improper configuration can lead to token leakage.\n\n**Dependency chain**\n- Depends on the authorization server's registered redirect URIs.\n- Used in conjunction with client_id and response_type parameters.\n- Integral to OAuth 2.0 authorization code and implicit grant flows.\n\n**Technical details**\n- Must conform to URI syntax as per RFC 3986.\n- Typically uses HTTPS scheme for security.\n- Should be URL-encoded when included in authorization requests.\n- The authorization server compares the redirect URI in the request with the registered URIs for exact match or pattern match depending on server policy."},"clientCredentialsLocation":{"type":"string","enum":["basicauthheader","body"],"description":"Specifies the location within the HTTP request where the client credentials (such as client ID and client secret) should be included when using the OAuth 2.0 client credentials grant type. This setting determines whether the credentials are sent in the request header (typically using the Authorization header with Basic authentication) or in the request body as form parameters.\n\n**Field behavior**\n- Defines where to place client credentials during the token request.\n- Accepts values indicating header or body placement.\n- Influences how the authentication server receives and validates client credentials.\n\n**Implementation guidance**\n- Use \"header\" to send credentials via the Authorization header using Basic authentication.\n- Use \"body\" to include credentials as form parameters in the POST request body.\n- Ensure compatibility with the OAuth 2.0 server’s expected credential location.\n- Validate that the chosen location aligns with security best practices and server requirements.\n\n**Examples**\n- \"header\" — client credentials sent in the Authorization header.\n- \"body\" — client credentials sent as form parameters in the request body.\n\n**Important notes**\n- Sending credentials in the header is generally preferred for security reasons.\n- Some OAuth 2.0 servers may only support one method; verify server documentation.\n- Incorrect configuration may lead to authentication failures.\n- Avoid exposing client credentials in URLs or query parameters.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 client credentials grant type being used.\n- Works in conjunction with clientId and clientSecret properties.\n- Affects the construction of the token request sent to the authorization server.\n\n**Technical details**\n- When set to \"header\", credentials are base64-encoded and included in the Authorization header.\n- When set to \"body\", credentials are included as \"client_id\" and \"client_secret\" form parameters.\n- Must comply with the OAuth 2.0 specification (RFC 6749) regarding client authentication methods."},"validDomainNames":{"type":"array","items":{"type":"string"},"description":"A list of domain names used to validate the OAuth URLs (Authorization, Access Token, Revoke Token).\n\nProvide each unique domain once (no scheme, no path).\n\n**Examples**\n- `[\"domain.com\"]`\n- `[\"domain.com\", \"domain1.com\", \"domain2.com\"]`\n\n**Technical details**\n- Stored as an array of strings."},"grantType":{"type":"string","enum":["authorizecode","password","clientcredentials"],"description":"Specifies the OAuth 2.0 grant type used to obtain an access token from the authorization server. This parameter determines the flow of the authentication process and how the client interacts with the authorization server to request and receive tokens. Common grant types include \"authorization_code\", \"client_credentials\", \"password\", and \"refresh_token\", each serving different use cases and security considerations.\n\n**Field behavior**\n- Defines the method by which the client application requests an access token.\n- Influences the parameters required in the token request.\n- Determines the security and user interaction model of the OAuth flow.\n- Must align with the authorization server's supported grant types.\n\n**Implementation guidance**\n- Choose the grant type based on the client application's capabilities and security requirements.\n- Ensure the authorization server supports the specified grant type.\n- Validate the grant type value against the OAuth 2.0 specification and any extensions used.\n- Handle errors gracefully if an unsupported or invalid grant type is provided.\n\n**Examples**\n- \"authorization_code\" for standard web server flows involving user authorization.\n- \"client_credentials\" for machine-to-machine authentication without user involvement.\n- \"password\" for legacy applications where the user provides credentials directly.\n- \"refresh_token\" to obtain a new access token using a previously issued refresh token.\n\n**Important notes**\n- Some grant types require additional parameters (e.g., \"authorization_code\" requires a code).\n- Using the \"password\" grant type is discouraged due to security risks.\n- The choice of grant type affects the overall security posture of the application.\n- Always use secure communication channels (HTTPS) when transmitting tokens and credentials.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 authorization server configuration.\n- Influences the required request parameters and token endpoint behavior.\n- Affects client registration details and scopes granted.\n\n**Technical details**\n- Must be a string matching one of the OAuth 2.0 defined grant types or extensions.\n- Sent as a parameter in the token request payload or URL-encoded form.\n- Case-sensitive and must conform to the OAuth 2.0 specification (RFC 6749).\n- May require additional headers or parameters depending on the grant type."},"failPath":{"type":"string","description":"Path to the **auth error field** in the HTTP response body.\n\nThis field only needs to be set if the API returns a field in the HTTP response body to indicate auth errors.\nFor example, if an API returns the field `errorMessage` with the value `Auth failed`, then set this field to `errorMessage`.\n\n**Examples**\n- `errorMessage`\n- `error`\n- `errors.0.message`"},"failValues":{"type":"array","items":{"type":"string"},"description":"Values to match against the HTTP response body field identified by\n`failPath`. If any value matches, the response is treated as an\nauth failure.\n\n**Examples**\n- `[\"access_denied\", \"invalid_grant\"]`\n- `[\"error\"]`"},"failStatusCode":{"type":"number","description":"HTTP status code that indicates an OAuth2 authentication error.\n\nThis field only needs to be set if the system you are authenticating against uses a status code **other than 401** for auth errors.\nFor example, an API may return a generic `400` status code, and then use a field in the HTTP response body to indicate authentication errors.\n\n**Field behavior**\n- Determines the HTTP response status code sent upon OAuth2 failure.\n- Influences client-side error handling and user feedback.\n- Overrides default failure status codes if explicitly set.\n\n**Implementation guidance**\n- Leave unset if auth errors are returned as `401` (default behavior).\n- Set this if auth failures are returned using another status code (e.g., `400`).\n\n**Examples**\n- 401\n- 400\n\n**Important notes**\n- Setting an inappropriate status code may lead to client confusion or security risks.\n- Some clients or intermediaries may behave differently depending on the status code.\n- The status code should be accompanied by a descriptive error message in the response body.\n\n**Dependency chain**\n- Depends on OAuth2 authentication and authorization failure events.\n- Works in conjunction with error response payloads and headers.\n- May interact with logging and monitoring systems for failure tracking.\n\n**Technical details**\n- Must be an integer within the range of valid HTTP status codes (100–599).\n- Typically used in HTTP response status line.\n- Should be consistent with OAuth2 error response standards defined in RFC 6749."},"useNewAuthFailSchema":{"type":"boolean","readOnly":true,"description":"Server-managed flag indicating whether the newer auth-failure\ndetection schema is in effect. Always `true` in current API\nresponses. Do not set this field in requests."},"failures":{"type":"array","readOnly":true,"description":"Server-computed summary of the auth-failure detection rules\nderived from `failPath`, `failValues`, and `failStatusCode`.\nPresent in responses only when those fields are configured.","items":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code that triggers auth-failure detection."},"path":{"type":"string","description":"Response body path checked for failure values."},"values":{"type":"array","items":{"type":"string"},"description":"Values at `path` that indicate an auth failure."}}}},"accessTokenLocation":{"type":"string","enum":["url","header","body"],"description":"Specifies the location where the OAuth 2.0 access token should be included when making API requests. This determines how the access token is transmitted to the server, such as in the HTTP header, query parameters, or request body. Proper configuration of this field ensures that the token is sent in a manner compatible with the API's authentication requirements.\n**Field behavior**\n- Defines the method of including the access token in API requests.\n- Common values include \"header\", \"query\", or \"body\".\n- Influences how the client constructs the request for authentication.\n**Implementation guidance**\n- Verify the API specification to determine the supported token locations.\n- Use \"header\" to include the token in the Authorization header (e.g., Bearer token).\n- Use \"query\" to append the token as a URL query parameter.\n- Use \"body\" to include the token within the request payload, typically for POST requests.\n- Ensure secure transmission, especially when using query parameters.\n**Examples**\n- \"header\" — Access token sent in the Authorization header.\n- \"query\" — Access token appended as ?access_token=XYZ in the URL.\n- \"body\" — Access token included in the POST request body parameters.\n**Important notes**\n- Sending tokens in query parameters can expose them in logs or browser history; use with caution.\n- The chosen location must align with the OAuth 2.0 server's expectations.\n- Some APIs may only support one method; incorrect configuration can lead to authentication failures.\n**Dependency chain**\n- Depends on the OAuth 2.0 flow and server requirements.\n- Works in conjunction with the access token value and token type.\n- Influences request construction and security considerations.\n**Technical details**\n- When set to \"header\", typically uses the \"Authorization: Bearer \" format.\n- When set to \"query\", appends the token as a URL parameter, often named \"access_token\".\n- When set to \"body\", includes the token in the request payload, usually as a form parameter.\n- Must be handled securely to prevent token leakage."},"accessTokenHeaderName":{"type":["string","null"],"description":"Header name used to send the OAuth 2.0 access token.\n\n**Examples**\n- `Authorization` (typically with value `Bearer `)\n- `X-Access-Token`"},"accessTokenPath":{"type":"string","description":"Specifies the relative URL path on the OAuth2 authorization server where the access token request should be sent. This path is appended to the base URL of the authorization server to form the full endpoint for obtaining an access token during the OAuth2 authentication flow. It is essential for enabling clients to exchange authorization grants for access tokens securely.\n\n**Field behavior**\n- Defines the endpoint path for access token requests in the OAuth2 flow.\n- Must be a valid relative URL path starting with a forward slash (/).\n- Used during the token exchange phase after obtaining an authorization code or other grant types.\n- Typically combined with the authorization server's base URL to form the complete token endpoint URL.\n\n**Implementation guidance**\n- Ensure the path corresponds exactly to the OAuth2 server's token endpoint specification.\n- Validate that the path is correctly formatted and accessible.\n- Avoid including query parameters or fragments in this path; it should be a clean URL path.\n- Confirm compatibility with the OAuth2 server's expected token endpoint URL structure.\n\n**Examples**\n- /oauth2/token\n- /api/v1/access_token\n- /auth/token\n\n**Important notes**\n- This path is critical for the OAuth2 token exchange process; incorrect configuration will prevent successful authentication.\n- It should not include the full URL, only the path component.\n- Must align with the OAuth2 server's documentation to ensure interoperability.\n- Often used in conjunction with other OAuth2 properties like client ID, client secret, and authorization path.\n\n**Dependency chain**\n- Depends on the base URL of the OAuth2 authorization server.\n- Used alongside authorizationPath and other OAuth2 configuration properties.\n- Integral to the OAuth2 token grant process.\n\n**Technical details**\n- Expected to be a URI path string.\n- Should begin with a forward slash (/).\n- Combined with the OAuth2 server's base URL to form the full token endpoint URI.\n- Utilized in HTTP POST requests to obtain access tokens."},"refreshTokenPath":{"type":"string","description":"The relative or absolute URL path used to request a refresh token from the OAuth 2.0 authorization server. This endpoint is typically called when the current access token has expired or is about to expire, allowing the client to obtain a new access token without requiring the user to re-authenticate. The path should conform to the OAuth 2.0 specification for token refresh requests and support the necessary HTTP methods, usually POST.\n\n**Field behavior**\n- Specifies the endpoint for refreshing OAuth 2.0 access tokens.\n- Used by the client application to maintain authenticated sessions seamlessly.\n- Invoked automatically by the client when the access token expires or is near expiration.\n- Must be accessible and correctly configured on the authorization server.\n\n**Implementation guidance**\n- Ensure the path is correctly formatted as a relative or absolute URL.\n- Confirm that the authorization server supports refresh token requests at this endpoint.\n- Secure the endpoint with appropriate authentication and authorization measures.\n- Validate that the client credentials and refresh token are correctly handled during the request.\n- Handle error responses gracefully, such as invalid or expired refresh tokens.\n\n**Examples**\n- \"/oauth2/token/refresh\"\n- \"https://auth.example.com/oauth2/token\"\n- \"/api/v1/auth/refresh-token\"\n\n**Important notes**\n- This path is distinct from the initial token request endpoint.\n- The refresh token flow requires that the client has previously obtained a refresh token.\n- Not all OAuth 2.0 providers support refresh tokens; verify compatibility.\n- The endpoint must support secure communication protocols (e.g., HTTPS).\n\n**Dependency chain**\n- Depends on the existence of a valid refresh token issued during initial authentication.\n- Works in conjunction with the access token and client credentials.\n- Related to the OAuth 2.0 token endpoint configuration.\n\n**Technical details**\n- Typically uses the HTTP POST method with form-encoded parameters.\n- Requires parameters such as grant_type=refresh_token and the refresh_token itself.\n- Responses include a new access token and optionally a new refresh token.\n- Must handle scopes and token expiration as per OAuth 2.0 standards."},"scheme":{"type":"string","description":"Specifies the OAuth 2.0 authorization scheme used for securing API requests. This field defines the method by which the client obtains and presents access tokens to authenticate and authorize API calls. Common schemes include \"authorization_code\", \"implicit\", \"password\", and \"client_credentials\", each representing a different OAuth 2.0 flow tailored to various client types and security requirements.\n\n**Field behavior**\n- Determines the OAuth 2.0 flow applied for token acquisition.\n- Influences how clients interact with the authorization server.\n- Guides the expected parameters and endpoints involved in the authentication process.\n\n**Implementation guidance**\n- Choose the scheme that best fits the client application type and security context.\n- Ensure the scheme aligns with the OAuth 2.0 specification and server capabilities.\n- Clearly document the chosen scheme to aid client developers in implementation.\n\n**Examples**\n- \"authorization_code\" for server-side web applications.\n- \"implicit\" for single-page applications.\n- \"password\" for trusted applications with user credentials.\n- \"client_credentials\" for machine-to-machine authentication.\n\n**Important notes**\n- Selecting an inappropriate scheme can lead to security vulnerabilities.\n- Some schemes may require additional parameters or configurations.\n- The scheme impacts token lifecycle and refresh mechanisms.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 specification version supported.\n- Interacts with token endpoint and authorization endpoint configurations.\n- Influences client registration and credential management.\n\n**Technical details**\n- Typically represented as a string value.\n- Must conform to recognized OAuth 2.0 flow identifiers.\n- Used by client libraries to determine authentication steps."},"accessTokenParamName":{"type":"string","description":"Parameter name used when the access token is passed as a query/body parameter (instead of a header).\n\n**Examples**\n- `access_token`\n- `token`\n- `auth_token`"},"useIClientFields":{"type":"boolean","description":"Determines whether to utilize the legacy iClient-specific fields in the OAuth2 configuration instead of the standard OAuth2 fields. This option is typically used for backward compatibility with systems or integrations that rely on the older iClient field structure.\n\n**Field behavior**\n- When set to true, the system uses iClient-specific OAuth2 fields for authentication.\n- When set to false or omitted, the system defaults to standard OAuth2 fields.\n- Influences how client credentials and tokens are processed during OAuth2 flows.\n\n**Implementation guidance**\n- Enable this flag only if integrating with legacy systems requiring iClient fields.\n- Ensure that the corresponding iClient fields are properly configured when this is enabled.\n- Validate compatibility with the OAuth2 provider before enabling this option.\n\n**Examples**\n- true: Use iClient-specific fields for OAuth2 authentication.\n- false: Use standard OAuth2 fields for authentication.\n\n**Important notes**\n- Enabling this may affect interoperability with modern OAuth2 providers.\n- This setting is primarily for backward compatibility and may be deprecated in future releases.\n- Misconfiguration can lead to authentication failures.\n\n**Dependency chain**\n- Depends on the presence of iClient-specific OAuth2 fields in the configuration.\n- Affects OAuth2 token request and refresh processes.\n\n**Technical details**\n- Overrides default OAuth2 client ID, secret, and token endpoint parameters with iClient equivalents.\n- May alter request payload structure during OAuth2 token exchanges.\n- Typically used in environments where legacy iClient authentication flows are required."},"pkceCodeChallengeMethod":{"type":["string","null"],"enum":["plain","s256"],"description":"PKCE code challenge method used for the OAuth 2.0 authorization code flow (RFC 7636).\n\n**Field behavior**\n- `s256` is recommended.\n- `plain` should only be used if required by the provider.\n\n**Examples**\n- `s256`\n- `plain`"},"auth":{"type":"object","properties":{"uri":{"type":"string","description":"The URI endpoint where the OAuth 2.0 authorization server accepts authorization requests. This URI is used by clients to initiate the authorization flow, typically by redirecting the resource owner's user-agent to this address. It must be a valid HTTPS URL to ensure secure transmission of sensitive information such as authorization codes or tokens.\n\n**Field behavior**\n- Serves as the entry point for the OAuth 2.0 authorization process.\n- Used by clients to request authorization from the resource owner.\n- Typically involves redirection of the user's browser to this URI.\n- Must support standard OAuth 2.0 authorization request parameters.\n\n**Implementation guidance**\n- Ensure the URI is an HTTPS endpoint to maintain security.\n- The endpoint should conform to OAuth 2.0 specifications for authorization endpoints.\n- Validate that the URI is reachable and correctly configured to handle authorization requests.\n- Include necessary query parameters as per OAuth 2.0 standards during requests.\n\n**Examples**\n- https://authorization-server.com/oauth2/authorize\n- https://accounts.example.com/auth\n- https://login.provider.com/oauth2/auth\n\n**Important notes**\n- The URI must be registered with the OAuth 2.0 provider and match the client configuration.\n- Using HTTP instead of HTTPS is not recommended due to security risks.\n- The URI should be stable and not change frequently to avoid client misconfigurations.\n- This endpoint is distinct from the token endpoint used to exchange authorization codes for tokens.\n\n**Dependency chain**\n- Dependent on the OAuth 2.0 client configuration specifying this URI.\n- Used in conjunction with client_id, redirect_uri, response_type, and scope parameters.\n- Works alongside the token endpoint URI for completing the OAuth flow.\n\n**Technical details**\n- Must be a valid, well-formed URL.\n- Should support GET requests with query parameters for authorization requests.\n- Typically responds with redirects (HTTP 302) to the redirect_uri with authorization codes or tokens.\n- Should implement security best practices such as TLS 1.2+ and proper CORS policies."}},"description":"Specifies the authentication method and credentials required for OAuth 2.0 authorization. This property defines how the client should authenticate with the authorization server to obtain an access token. It typically includes details such as client ID, client secret, token endpoint, scopes, and grant type.\n\n**Field behavior**\n- Determines the authentication flow used in the OAuth 2.0 process.\n- Controls how credentials are presented to the authorization server.\n- Influences token acquisition and refresh mechanisms.\n- May include multiple authentication parameters depending on the grant type.\n\n**Implementation guidance**\n- Ensure all required fields for the chosen OAuth 2.0 flow are included.\n- Securely store sensitive information like client secrets.\n- Validate the format and correctness of URLs and credentials.\n- Support common grant types such as authorization code, client credentials, and password.\n- Handle token expiration and refresh logic as needed.\n\n**Examples**\n- Client credentials flow with client ID and client secret.\n- Authorization code flow with redirect URI and scopes.\n- Password grant with username and password fields.\n- Refresh token usage for renewing access tokens.\n\n**Important notes**\n- Sensitive data must be protected and not exposed in logs or error messages.\n- The authentication method must comply with OAuth 2.0 standards.\n- Misconfiguration can lead to failed authentication or security vulnerabilities.\n- Different OAuth 2.0 providers may require specific parameters or formats.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 grant type specified elsewhere in the configuration.\n- Interacts with token endpoint URLs and scope definitions.\n- May be linked to client application registration details.\n\n**Technical details**\n- Typically includes fields such as client_id, client_secret, token_url, scopes, grant_type.\n- May require encoding or encryption of credentials during transmission.\n- Supports standard OAuth 2.0 token request and response formats.\n- Should handle HTTP status codes and error responses from the authorization server."},"token":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method used to call the OAuth 2.0 token endpoint.\n\n**Important notes**\n- `POST` is most common and recommended.\n- `GET` may expose sensitive data in URLs/logs."},"uri":{"type":"string","description":"The URI (Uniform Resource Identifier) specifying the endpoint where the OAuth 2.0 token request is sent to obtain an access token. This endpoint is responsible for authenticating the client and issuing tokens according to the OAuth 2.0 protocol. It must be a valid HTTPS URL to ensure secure transmission of sensitive credentials and tokens.\n\n**Field behavior**\n- Defines the exact URL to which token requests are made during the OAuth 2.0 flow.\n- Used by clients to exchange authorization grants or refresh tokens for access tokens.\n- Must support the OAuth 2.0 token request parameters and response formats.\n- Typically accessed via HTTP POST requests.\n\n**Implementation guidance**\n- Ensure the URI is a fully qualified HTTPS URL to maintain security.\n- Confirm the endpoint supports the OAuth 2.0 token exchange specification.\n- Validate the URI format before use to prevent runtime errors.\n- Document any additional headers or parameters required by the token endpoint.\n\n**Examples**\n- https://auth.example.com/oauth2/token\n- https://login.provider.com/oauth2/v1/token\n- https://api.service.com/oauth/token\n\n**Important notes**\n- The URI must be reachable and responsive to token requests.\n- Using HTTP instead of HTTPS is discouraged due to security risks.\n- The token endpoint may require client authentication via headers or request body.\n- Changes to this URI can disrupt the OAuth 2.0 authentication flow.\n\n**Dependency chain**\n- Dependent on the OAuth 2.0 authorization server configuration.\n- Used in conjunction with client credentials and grant types.\n- Related to other OAuth 2.0 endpoints such as authorization URI and revocation URI.\n\n**Technical details**\n- Must conform to URI syntax as per RFC 3986.\n- Typically accessed using HTTP POST with content type application/x-www-form-urlencoded.\n- Responses are usually JSON objects containing access tokens and metadata.\n- May support additional OAuth 2.0 extensions like PKCE or client authentication methods."},"body":{"type":"string","description":"The body property represents the payload content sent in the HTTP request when obtaining an OAuth 2.0 token. It typically includes key-value pairs such as grant type, client credentials, authorization code, refresh token, and scope, formatted according to the OAuth 2.0 specification. This property is essential for conveying the necessary parameters to the token endpoint to successfully authenticate and receive an access token.\n\n**Field behavior**\n- Contains the data sent in the HTTP request body during the token request.\n- Must include all required parameters based on the OAuth 2.0 grant type being used.\n- Often formatted as application/x-www-form-urlencoded or JSON, depending on the API requirements.\n- Is transmitted securely over HTTPS to protect sensitive information.\n\n**Implementation guidance**\n- Ensure the body includes all mandatory fields such as grant_type, client_id, client_secret, code, redirect_uri, or refresh_token as applicable.\n- Use the correct content type header matching the body format.\n- Encode parameters properly to comply with URL encoding standards if using form-urlencoded format.\n- Validate the body content before sending to avoid malformed requests.\n\n**Examples**\n- grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback&client_id=CLIENT_ID&client_secret=CLIENT_SECRET\n- { \"grant_type\": \"refresh_token\", \"refresh_token\": \"REFRESH_TOKEN\", \"client_id\": \"CLIENT_ID\" }\n\n**Important notes**\n- The exact parameters required in the body depend on the OAuth 2.0 flow implemented (authorization code, client credentials, password, refresh token).\n- Sensitive information such as client_secret should be handled securely and never exposed in logs or client-side code.\n- The body must conform to the OAuth 2.0 specification and the authorization server’s expectations.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 grant type selected.\n- Relies on correct client credentials and authorization codes obtained from prior steps.\n- Works in conjunction with HTTP headers like Content-Type and Authorization.\n\n**Technical details**\n- Typically sent as application/x-www-form-urlencoded or application/json.\n- Must be included in the POST request to the token endpoint URL.\n- Parameters are case-sensitive and must match the OAuth 2.0 specification.\n- The server response depends on the correctness and completeness of the body content."},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the token request when obtaining an OAuth 2.0 access token. These headers allow customization of the request, such as setting content types, authorization credentials, or custom metadata required by the token endpoint. The headers should be specified as key-value pairs where the key is the header name and the value is the header content.\n\n**Field behavior**\n- Overrides or supplements default headers sent in the token request.\n- Supports multiple headers to be included simultaneously.\n- Headers are sent exactly as specified without modification.\n- Used primarily during the OAuth 2.0 token exchange process.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized as per HTTP standards.\n- Avoid including sensitive information unless required and secure.\n- Validate header values to conform to expected formats (e.g., content-type).\n- Use this field to add custom headers required by specific OAuth providers.\n\n**Examples**\n- Authorization: Basic base64(client_id:client_secret)\n- Content-Type: application/x-www-form-urlencoded\n- Custom-Header: customValue\n\n**Important notes**\n- Headers specified here apply only to the token request, not to other OAuth flows.\n- Conflicts with default headers may cause token request failures.\n- Sensitive headers should be handled securely to prevent leaks.\n- Some OAuth providers may require specific headers for successful authentication.\n\n**Dependency chain**\n- Used in conjunction with oauth2.token.url and oauth2.token.body parameters.\n- May depend on client credentials or other authentication parameters.\n- Influences the HTTP request sent to the OAuth token endpoint.\n\n**Technical details**\n- Represented as a map/dictionary of string keys and string values.\n- Transmitted as HTTP headers in the token request POST or GET.\n- Supports standard HTTP header syntax and conventions.\n- Must comply with OAuth 2.0 token endpoint requirements and HTTP protocol."}},"description":"The access token issued by the OAuth 2.0 authorization server, used to authenticate and authorize API requests on behalf of the user or client. This token is typically a string representing a bearer token that must be included in the Authorization header of HTTP requests to access protected resources. It has a limited lifetime and scope, defining the permissions granted to the client.\n\n**Field behavior**\n- Represents the credential used to access protected resources.\n- Must be included in API requests to authenticate the client.\n- Has an expiration time after which it becomes invalid.\n- May be a JWT or opaque string depending on the authorization server.\n- Should be securely stored and transmitted only over HTTPS.\n\n**Implementation guidance**\n- Ensure the token is included in the Authorization header as \"Bearer {token}\".\n- Validate the token's expiration and scope before use.\n- Refresh the token using a refresh token if supported and expired.\n- Handle token revocation and errors gracefully.\n- Avoid logging or exposing the token in client-side code or URLs.\n\n**Examples**\n- \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n- \"2YotnFZFEjr1zCsicMWpAA\"\n- \"mF_9.B5f-4.1JqM\"\n\n**Important notes**\n- The token must be kept confidential to prevent unauthorized access.\n- Tokens are typically short-lived to enhance security.\n- Different APIs may require tokens with specific scopes or claims.\n- Always use secure transport (HTTPS) when transmitting tokens.\n\n**Dependency chain**\n- Obtained after successful OAuth 2.0 authorization or token exchange.\n- May depend on client credentials, authorization code, or refresh token.\n- Used in conjunction with the Authorization header in API requests.\n\n**Technical details**\n- Usually a string encoded in JWT or opaque format.\n- Contains claims or metadata about the user and permissions.\n- Includes an expiration timestamp (exp claim in JWT).\n- May include scopes defining access rights.\n- Must conform to OAuth 2.0 and OpenID Connect standards where applicable."},"refresh":{"type":"object","properties":{"body":{"type":"string","description":"The body of the HTTP request used to refresh an OAuth 2.0 access token. This typically includes parameters such as the refresh token, client credentials, grant type, and any additional required fields as specified by the OAuth 2.0 protocol. The body must be formatted according to the content type expected by the authorization server, commonly application/x-www-form-urlencoded.\n\n**Field behavior**\n- Contains all necessary parameters to request a new access token using a refresh token.\n- Must include the \"grant_type\" parameter set to \"refresh_token\".\n- Should include the \"refresh_token\" parameter with the valid refresh token value.\n- May include client authentication parameters such as \"client_id\" and \"client_secret\" if required.\n- Sent as the payload of the HTTP POST request to the token endpoint.\n\n**Implementation guidance**\n- Ensure the body is properly URL-encoded if using application/x-www-form-urlencoded content type.\n- Validate that all required parameters are present before sending the request.\n- Follow the OAuth 2.0 specification (RFC 6749) for the exact parameter names and values.\n- Handle any additional parameters required by the specific OAuth provider.\n- Securely handle sensitive information such as client secrets and refresh tokens.\n\n**Examples**\n- grant_type=refresh_token&refresh_token=xyz123&client_id=abc&client_secret=secret\n- grant_type=refresh_token&refresh_token=def456\n\n**Important notes**\n- The refresh token must be valid and not expired or revoked.\n- The authorization server may require client authentication in the body or via other means.\n- The content type header must match the format of the body (e.g., application/x-www-form-urlencoded).\n- Improper formatting or missing parameters will result in an error response from the server.\n\n**Dependency chain**\n- Depends on having a valid refresh token obtained from a previous authorization.\n- Requires knowledge of the OAuth 2.0 token endpoint URL.\n- May depend on client credentials if the server requires client authentication.\n- Relies on the correct grant_type parameter to indicate a refresh token request.\n\n**Technical details**\n- Typically sent as an HTTP POST request body.\n- Commonly uses application/x-www-form-urlencoded encoding.\n- Parameters include \"grant_type\", \"refresh_token\", and optionally \"client_id\" and \"client_secret\".\n- Must comply with OAuth 2.0 RFC 6749 Section 6 for token refresh requests."},"method":{"type":"string","enum":["GET","POST"],"description":"Specifies the HTTP method to be used when making the refresh token request in the OAuth 2.0 authentication flow. This method determines how the refresh token and related parameters are sent to the authorization server to obtain a new access token. Common HTTP methods include POST and GET, with POST being the most widely used due to its ability to securely transmit data in the request body.\n\n**Field behavior**\n- Defines the HTTP verb for the token refresh request.\n- Influences how parameters are encoded and transmitted.\n- Affects compatibility with different OAuth 2.0 server implementations.\n\n**Implementation guidance**\n- Typically set to POST for secure transmission of sensitive data.\n- Ensure the chosen method aligns with the OAuth 2.0 server’s requirements.\n- Validate that the client library or HTTP client supports the specified method.\n- Consider security implications of using GET, as parameters may be exposed in URLs.\n\n**Examples**\n- POST\n- GET\n\n**Important notes**\n- Using GET may expose refresh tokens in URLs, which can be logged or cached.\n- Some OAuth 2.0 servers may only support POST for token refresh requests.\n- The method must be consistent with the server’s expected protocol to avoid errors.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 server’s token endpoint configuration.\n- Interacts with the refresh token and client credentials parameters.\n- Influences the HTTP headers and body formatting of the request.\n\n**Technical details**\n- HTTP methods are case-insensitive but typically uppercase.\n- POST requests send parameters in the request body using application/x-www-form-urlencoded format.\n- GET requests send parameters as URL query parameters.\n- Proper handling of HTTP status codes and responses is required based on the method used."},"uri":{"type":"string","description":"Refresh token endpoint URI used to exchange a refresh token for a new access token (RFC 6749 Section 6).\n\n**Examples**\n- https://auth.example.com/oauth2/token\n- https://login.provider.com/oauth2/v1/token"},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the OAuth 2.0 refresh token request. These headers can be used to pass additional metadata, authentication information, or custom parameters required by the authorization server during the token refresh process. Typically, this may include headers such as `Content-Type`, `Authorization`, or any other custom headers mandated by the API specification.\n\n**Field behavior**\n- Accepts key-value pairs representing HTTP header names and their corresponding values.\n- Headers are included in the HTTP request sent to the token endpoint during the refresh token flow.\n- Overrides or supplements default headers set by the client or HTTP library.\n- Supports standard and custom headers as required by the OAuth 2.0 provider.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized and conform to HTTP standards.\n- Avoid including sensitive information in headers unless required and secured.\n- Validate header values to prevent injection or formatting errors.\n- Use this field to add headers like `Authorization` if the token endpoint requires client authentication via headers.\n- Do not duplicate headers that are automatically managed by the HTTP client unless overriding is necessary.\n\n**Examples**\n- `Content-Type: application/x-www-form-urlencoded`\n- `Authorization: Basic base64(client_id:client_secret)`\n- `Custom-Header: customValue`\n\n**Important notes**\n- Headers specified here apply only to the refresh token request, not to other OAuth 2.0 flows.\n- Misconfigured headers can cause token refresh failures or security issues.\n- Some OAuth 2.0 servers require specific headers for token refresh requests; consult the provider’s documentation.\n- Sensitive headers should be handled securely to prevent exposure.\n\n**Dependency chain**\n- Used in conjunction with `oauth2.refresh.tokenUrl` to make the refresh token request.\n- May depend on client authentication method specified elsewhere in the OAuth 2.0 configuration.\n- Interacts with HTTP client settings that manage default headers.\n\n**Technical details**\n- Represented as a map/dictionary of string keys and string values.\n- Translated into HTTP headers in the outgoing POST request to the token endpoint.\n- Must comply with HTTP/1.1 header field syntax and encoding rules.\n- Typically sent over HTTPS to ensure confidentiality and integrity."}},"description":"Indicates whether the OAuth2 refresh token flow is supported/enabled.\n\n**Examples**\n- `true`\n- `false`"},"revoke":{"type":"object","properties":{"uri":{"type":"string","description":"The URI endpoint where OAuth 2.0 token revocation requests are sent. This URI is used by clients to invalidate access or refresh tokens, ensuring they can no longer be used for authentication or authorization. It must be a valid HTTPS URL to guarantee secure transmission of sensitive token data.\n\n**Field behavior**\n- Accepts a single string value representing the revocation endpoint URL.\n- Used by clients to send HTTP POST requests to revoke tokens.\n- Should support standard OAuth 2.0 token revocation parameters as per RFC 7009.\n- Must be reachable and respond appropriately to revocation requests.\n\n**Implementation guidance**\n- Ensure the URI uses HTTPS to protect token data during transmission.\n- The endpoint should conform to OAuth 2.0 Token Revocation specification (RFC 7009).\n- Validate the URI format to prevent misconfiguration.\n- Document any additional headers or authentication required by the revocation endpoint.\n\n**Examples**\n- https://auth.example.com/oauth2/revoke\n- https://api.service.com/oauth2/token/revoke\n\n**Important notes**\n- The revocation URI is distinct from the authorization and token endpoints.\n- Proper implementation of token revocation enhances security by allowing clients to invalidate tokens when no longer needed.\n- Failure to provide a valid revocation URI may prevent clients from properly revoking tokens.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 authorization server configuration.\n- Related to the OAuth 2.0 token endpoint and authorization endpoint.\n- Used in conjunction with client credentials and tokens issued by the authorization server.\n\n**Technical details**\n- Typically accessed via HTTP POST with parameters such as token and token_type_hint.\n- Must handle authentication of the client making the revocation request.\n- Should return appropriate HTTP status codes indicating success or failure of revocation."},"body":{"type":"string","description":"The request body containing the parameters required to revoke an OAuth 2.0 token. This typically includes the token to be revoked and may also specify the token type hint to indicate whether the token is an access token or a refresh token. The body must be formatted according to the application/x-www-form-urlencoded MIME type as per the OAuth 2.0 Token Revocation specification (RFC 7009).\n\n**Field behavior**\n- Contains key-value pairs representing the token and optional token type hint.\n- Must be included in the HTTP POST request to the token revocation endpoint.\n- Parameters are URL-encoded in the request body.\n- Used to instruct the authorization server to invalidate a specific token.\n\n**Implementation guidance**\n- Ensure the body includes the \"token\" parameter with the token string to revoke.\n- Optionally include \"token_type_hint\" with values like \"access_token\" or \"refresh_token\" to assist the server.\n- Use application/x-www-form-urlencoded content type for the request.\n- Validate that the token parameter is present and correctly formatted before sending.\n- Handle server responses to confirm successful revocation or errors.\n\n**Examples**\n- token=SlAV32hkKG\n- token=34xkj23j4k23&token_type_hint=refresh_token\n- token=abcdef123456&token_type_hint=access_token\n\n**Important notes**\n- The token parameter is mandatory; omission will result in an error.\n- The token_type_hint is optional but recommended to improve server processing.\n- Revocation requests must be authenticated as per the authorization server’s requirements.\n- Revoking a token invalidates it immediately, preventing further use.\n- The body must not contain any additional parameters beyond those defined by the specification.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 token revocation endpoint being correctly configured.\n- Requires the client to have a valid token to revoke.\n- May depend on client authentication credentials included in the request headers.\n- The server’s response depends on the correctness of the body parameters.\n\n**Technical details**\n- Content-Type: application/x-www-form-urlencoded\n- Encoding: URL-encoded key-value pairs\n- Parameters:\n - token (string, required): The token to be revoked.\n - token_type_hint (string, optional): A hint about the type of the token.\n- HTTP Method: POST\n- Conforms to RFC 7009 (OAuth 2.0 Token Revocation)"},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the token revocation request for OAuth 2.0. These headers can be used to specify additional metadata such as content type, authorization credentials, custom client information, or any other required HTTP headers that the revocation endpoint expects. This allows for greater flexibility and control over the HTTP request sent to the authorization server when revoking tokens.\n\n**Field behavior**\n- Accepts key-value pairs representing HTTP header names and their corresponding values.\n- Headers are included in the HTTP request sent to the token revocation endpoint.\n- Can override default headers or add custom headers as needed.\n- Supports standard headers like `Authorization`, `Content-Type`, and custom headers.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized and conform to HTTP standards.\n- Avoid including sensitive information in headers unless required and secure.\n- Validate header values to prevent injection or formatting errors.\n- Use this field to comply with specific OAuth 2.0 server requirements for token revocation.\n\n**Examples**\n- `Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0`\n- `Content-Type: application/x-www-form-urlencoded`\n- `X-Custom-Header: customValue`\n\n**Important notes**\n- Headers specified here will be sent only during the token revocation request.\n- Misconfigured headers may cause the revocation request to fail.\n- This field does not affect other OAuth 2.0 requests such as token acquisition or introspection.\n\n**Dependency chain**\n- Used in conjunction with the `oauth2.revoke.url` property specifying the revocation endpoint.\n- May depend on `oauth2.revoke.method` to determine the HTTP method used.\n- Works alongside other OAuth 2.0 configuration properties to complete the revocation flow.\n\n**Technical details**\n- Represented as a map or dictionary of string key-value pairs.\n- Incorporated into the HTTP request headers when making the revocation call.\n- Must comply with HTTP header syntax and encoding rules.\n- Typically used in HTTP POST requests to the revocation endpoint."}},"description":"Indicates whether the OAuth2 token revocation endpoint is supported/enabled (RFC 7009).\n\n**Examples**\n- `true`\n- `false`"},"username":{"type":"string","description":"The username used to authenticate the user within the OAuth2 authorization framework. This value typically represents the unique identifier assigned to the user by the authentication provider or system. It is required when performing resource owner password credentials grant or other flows that involve direct user authentication.\n\n**Field behavior**\n- Must be a non-empty string representing the user's login identifier.\n- Used in conjunction with the password to obtain an access token.\n- Should be case-sensitive depending on the authentication system.\n- Validated against the authentication provider's user database.\n\n**Implementation guidance**\n- Ensure the username is securely transmitted over HTTPS to protect user credentials.\n- Validate the format and existence of the username before processing authentication.\n- Avoid logging the username in plain text to maintain user privacy.\n- Support international characters if the authentication system allows.\n\n**Examples**\n- \"johndoe\"\n- \"user@example.com\"\n- \"alice123\"\n\n**Important notes**\n- The username must correspond to a valid user account in the OAuth2 provider.\n- Incorrect usernames will result in authentication failure.\n- Should be handled securely to prevent exposure of sensitive user information.\n\n**Dependency chain**\n- Typically used alongside the `password` property in OAuth2 password grant flows.\n- Dependent on the OAuth2 server's user management and authentication mechanisms.\n\n**Technical details**\n- Data type: string\n- Maximum length may vary depending on the OAuth2 provider.\n- Should be URL-encoded if included in query parameters or request bodies."},"password":{"type":"string","description":"The OAuth2 **password** value (used with the password grant).\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores the password encrypted at rest (for example as `password_crypt`/`password_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a password is already set.\n\n**Implementation guidance**\n- Provide the plain password value here to set/update it.\n- To keep the existing password unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"unencrypted":{"type":"object","description":"Store all **non-sensitive** fields required by your imports and exports to access the app you are connecting to.\n\nThese values can be referenced by resources within integrator.io through the iClient.\n\n**Examples**\n- `{\"email\":\"my_email@company.com\", \"accountId\": \"8675301\", \"role\":\"admin\"}`\n\n**Important notes**\n- Only store non-sensitive values here (safe to store unencrypted).\n- Use `encrypted` for secrets (passwords, tokens, keys)."},"encrypted":{"type":"object","description":"Store all **sensitive** fields required by your imports and exports to access the app you are connecting to.\n\nThese values are stored with **AES-256 encryption** and other layers of protection to keep your data safe.\nThese values can be referenced by resources within integrator.io through the iClient.\n\n**Examples**\n- `{\"password\":\"celigorocks\"}`\n- `{\"token\":\"x7if4nkovhgr63ghp\"}`\n\n**Important notes**\n- Use this for secrets (passwords, tokens, keys).\n- Values may be masked (e.g., `\"******\"`) in API responses once stored."}},"description":"Configuration settings for OAuth 2.0 authentication, enabling secure authorization and access delegation for API clients. This property typically includes details such as authorization URLs, token URLs, scopes, client credentials, and grant types supported by the OAuth 2.0 provider.\n\n**Field behavior**\n- Defines the OAuth 2.0 flow and parameters required for client authentication.\n- Specifies the endpoints for obtaining authorization and access tokens.\n- Lists the scopes that determine the level of access granted.\n- Supports multiple OAuth 2.0 grant types (e.g., authorization code, client credentials).\n- Enables secure token exchange and refresh mechanisms.\n\n**Implementation guidance**\n- Ensure URLs for authorization and token endpoints are accurate and reachable.\n- Clearly define the scopes to limit access according to least privilege principles.\n- Include client ID and client secret securely, avoiding exposure in client-side code.\n- Support refresh tokens if long-lived sessions are required.\n- Validate tokens on the server side to maintain security.\n\n**Examples**\n- Authorization code flow with authorization URL, token URL, and scopes.\n- Client credentials flow with token URL and client credentials.\n- Implicit flow configuration for single-page applications.\n- Refresh token configuration for renewing access tokens.\n\n**Important notes**\n- OAuth 2.0 configurations must comply with the security best practices to prevent token leakage.\n- Sensitive information such as client secrets should never be exposed publicly.\n- The choice of grant type depends on the client application type and security requirements.\n- Proper error handling should be implemented for token acquisition failures.\n\n**Dependency chain**\n- Depends on the presence of an OAuth 2.0 compliant authorization server.\n- Requires secure storage and transmission of client credentials.\n- Interacts with API endpoints that enforce OAuth 2.0 token validation.\n\n**Technical details**\n- Typically includes fields like authorizationUrl, tokenUrl, refreshUrl, scopes, clientId, clientSecret, and grantTypes.\n- Uses HTTPS endpoints to ensure secure communication.\n- May support PKCE (Proof Key for Code Exchange) for enhanced security in public clients.\n- Tokens are usually JWTs or opaque tokens depending on the OAuth provider implementation."},"salesforce":{"type":"object","properties":{"clientId":{"type":"string","description":"The unique identifier assigned to a client application by Salesforce during the OAuth client registration process. This ID is used to authenticate the client when making API requests and establishing a secure connection with Salesforce services. It is essential for enabling authorized access to Salesforce resources on behalf of the client application.\n**Field behavior**\n- Must be a non-empty string.\n- Used as part of the OAuth authentication flow.\n- Typically remains constant for a given client application.\n- Required for initiating API calls to Salesforce.\n**Implementation guidance**\n- Obtain this value from the Salesforce connected app configuration.\n- Store securely and avoid exposing it in client-side code.\n- Validate the format to ensure it matches Salesforce client ID patterns.\n- Use in conjunction with clientSecret for authentication.\n**Examples**\n- \"3MVG9d6T2QxX9z5l7Y8P0qR1sT2uVwXyZAbCdEfGhIjKlMnOpQrStUvWxYz123456\"\n- \"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\"\n**Important notes**\n- The clientId alone does not grant access; it must be paired with appropriate credentials and tokens.\n- Changing the clientId requires updating all integrations using it.\n- Keep the clientId confidential to prevent unauthorized access.\n**Dependency chain**\n- Dependent on the Salesforce connected app setup.\n- Works alongside clientSecret, redirectUri, and OAuth tokens.\n- Required for generating access tokens.\n**Technical details**\n- Typically a 40-character alphanumeric string.\n- Assigned by Salesforce upon connected app creation.\n- Used in HTTP headers or request parameters during OAuth flows."},"clientSecret":{"type":"string","description":"The Salesforce OAuth **client secret** value.\n\nThis is the value you provide to configure or update the Salesforce iClient. Internally, integrator.io stores this secret encrypted at rest (for example as `clientSecret_crypt` and `clientSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a secret is already set.\n\n**Implementation guidance**\n- Provide the plain client secret value here to set/update it.\n- To keep the existing secret unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"apiToken":{"type":"string","description":"The API token used to authenticate requests to the Salesforce API. This token acts as a secure credential that grants access to Salesforce resources and operations, ensuring that only authorized clients can interact with the Salesforce environment. It is typically generated within Salesforce or through an OAuth flow and must be kept confidential to prevent unauthorized access.\n\n**Field behavior**\n- Used for authenticating API calls to Salesforce.\n- Must be included in the authorization header or as specified by the Salesforce API.\n- Typically has an expiration time and may require periodic renewal.\n- Invalid or expired tokens will result in authentication errors.\n\n**Implementation guidance**\n- Store the token securely, such as in environment variables or secure vaults.\n- Avoid hardcoding the token in source code or exposing it in logs.\n- Implement token refresh logic if using OAuth tokens with limited lifespans.\n- Validate the token format before use to prevent malformed requests.\n\n**Examples**\n- A long alphanumeric string like \"00Dxx0000001gPFEAY!AQ0AQJ...\"\n- OAuth access tokens obtained via Salesforce OAuth 2.0 flows.\n- Tokens generated from Salesforce connected apps for API access.\n\n**Important notes**\n- The API token is sensitive information and should be treated like a password.\n- Sharing or leaking the token can compromise Salesforce data security.\n- Ensure compliance with Salesforce security policies when handling tokens.\n- Different Salesforce environments (non-production vs production) may require different tokens.\n\n**Dependency chain**\n- Dependent on Salesforce user credentials or OAuth authorization flows.\n- Used in conjunction with the Salesforce instance URL and API endpoints.\n- May require additional headers or parameters as per Salesforce API specifications.\n\n**Technical details**\n- Typically included in HTTP headers as \"Authorization: Bearer {apiToken}\".\n- May have scopes or permissions associated depending on how it was generated.\n- Tokens may be JWTs or opaque strings depending on the authentication method.\n- Salesforce APIs validate the token on each request to authorize access."},"privateKey":{"type":"string","description":"The Salesforce private key value used for authentication flows such as JWT bearer token OAuth.\n\nThis is the value you provide to configure or update the Salesforce iClient. Internally, integrator.io stores this key encrypted at rest (for example as `privateKey_crypt`/`privateKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a key is already set.\n\n**Implementation guidance**\n- Provide the plaintext private key value here to set/update it (often PEM formatted).\n- To keep the existing private key unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"publicKey":{"type":"string","description":"The publicKey property represents the public cryptographic key used for secure data encryption, verification, or authentication processes within the Salesforce integration. This key is typically part of a public-private key pair and is used to encrypt data or verify digital signatures without exposing the private key. It ensures secure communication and data integrity between systems.\n\n**Field behavior**\n- Accepts a string value representing the public key in a standard format (e.g., PEM, DER).\n- Used to encrypt data or verify signatures in cryptographic operations.\n- Must be provided in a format compatible with the consuming system.\n- Immutable once set for a given integration instance to maintain security.\n\n**Implementation guidance**\n- Ensure the public key is generated using a secure and recognized cryptographic algorithm (e.g., RSA, ECDSA).\n- Validate the key format before accepting it to prevent errors during cryptographic operations.\n- Store the key securely and restrict access to prevent unauthorized modifications.\n- Update the key only through a controlled process to avoid breaking integrations.\n\n**Examples**\n- A PEM-encoded RSA public key string starting with \"-----BEGIN PUBLIC KEY-----\".\n- An ECDSA public key represented in base64 encoding.\n- A public key string used to verify JWT tokens issued by Salesforce.\n\n**Important notes**\n- The publicKey must correspond to the private key held securely by the entity performing signing or decryption.\n- Do not expose the private key in any API or configuration.\n- Incorrect or malformed keys will cause authentication or encryption failures.\n- Keep the key updated in case of key rotation policies.\n\n**Dependency chain**\n- Dependent on the cryptographic algorithm and key pair generation process.\n- Used by authentication, encryption, or signature verification components.\n- May be linked to other security configurations such as certificates or token validation settings.\n\n**Technical details**\n- Typically encoded in PEM or DER format.\n- May include metadata such as key type and length.\n- Should comply with relevant security standards (e.g., PKCS#1, X.509).\n- Size and algorithm choice affect security strength and performance."}},"description":"Configuration settings and credentials required to integrate with Salesforce, enabling seamless data synchronization and interaction with Salesforce APIs. This property typically includes authentication details, API endpoints, and any necessary parameters for establishing a secure connection to a Salesforce instance.\n\n**Field behavior**\n- Holds all necessary information to authenticate and communicate with Salesforce services.\n- Used to configure API calls for data retrieval, updates, and other Salesforce operations.\n- May include nested objects or fields such as client ID, client secret, access tokens, instance URLs, and API versions.\n\n**Implementation guidance**\n- Ensure sensitive information like client secrets and access tokens are securely stored and transmitted.\n- Validate the presence and correctness of required fields before attempting Salesforce integration.\n- Support token refresh mechanisms if applicable to maintain session validity.\n- Allow configuration flexibility to support different Salesforce environments (e.g., non-production, production).\n\n**Examples**\n- An object containing OAuth credentials: client_id, client_secret, refresh_token, and instance_url.\n- Configuration specifying API version and endpoint URLs.\n- JSON structure with nested authentication and connection parameters.\n\n**Important notes**\n- Proper error handling should be implemented for authentication failures or API call errors.\n- Salesforce API limits and quotas should be considered when designing integration logic.\n- Secure handling of credentials is critical to prevent unauthorized access.\n- The structure and required fields may vary depending on the Salesforce API version and authentication method used.\n\n**Dependency chain**\n- Dependent on Salesforce authentication mechanisms (OAuth 2.0, username-password flow, etc.).\n- Relies on network connectivity to Salesforce endpoints.\n- May depend on external libraries or SDKs for Salesforce API interaction.\n\n**Technical details**\n- Typically involves OAuth 2.0 tokens or username-password credentials.\n- Uses HTTPS for secure communication with Salesforce REST or SOAP APIs.\n- May include refresh token logic to maintain long-term access.\n- Supports configuration of API versioning to align with Salesforce API changes."},"ebay":{"type":"object","properties":{"appId":{"type":"string","description":"The unique identifier assigned to an application registered with the eBay developer program. This ID is used to authenticate API requests and associate them with a specific application.\n\n**Field behavior**\n- Must be included in API requests to identify the calling application.\n- Typically a string consisting of alphanumeric characters.\n- Used to track usage and enforce rate limits for the application.\n- Required for accessing most eBay APIs.\n\n**Implementation guidance**\n- Obtain the appId by registering your application on the eBay Developer Program portal.\n- Keep the appId confidential to prevent unauthorized use.\n- Include the appId in the request headers or parameters as specified by the API documentation.\n- Validate the appId format before sending requests to avoid errors.\n\n**Examples**\n- \"12345678-1234-1234-1234-123456789abc\"\n- \"MyEbayAppID2024\"\n- \"APP-9876543210\"\n\n**Important notes**\n- The appId is different from other eBay credentials such as client ID or client secret.\n- Using an invalid or expired appId will result in authentication errors.\n- Do not share your appId publicly to protect your application's security.\n\n**Dependency chain**\n- Depends on successful registration with the eBay Developer Program.\n- Used in conjunction with other authentication credentials like OAuth tokens.\n- Required before making authorized API calls.\n\n**Technical details**\n- Typically a UUID or a unique string assigned by eBay.\n- Passed as part of HTTP headers or query parameters depending on the API.\n- Used by eBay servers to identify and authenticate the application making the request."},"devId":{"type":"string","description":"The unique identifier assigned to a developer or development team by eBay. This ID is used to authenticate and track API usage associated with the developer's applications. It ensures that API requests are properly attributed and helps manage access permissions and rate limits.\n\n**Field behavior**\n- Must be included in API requests requiring developer authentication.\n- Used to identify the source of API calls.\n- Typically remains constant for a given developer or development team.\n- Should be kept confidential to prevent unauthorized use.\n\n**Implementation guidance**\n- Obtain the devId by registering as a developer on the eBay Developer Program portal.\n- Include the devId in all relevant API request headers or parameters as specified by eBay.\n- Store the devId securely in your application environment.\n- Do not expose the devId in client-side code or public repositories.\n\n**Examples**\n- \"1234567890\"\n- \"dev_abcdef123456\"\n- \"9876543210\"\n\n**Important notes**\n- The devId is distinct from other eBay identifiers such as appId, certId, or auth tokens.\n- Misuse or leakage of the devId can lead to unauthorized API access.\n- Changes to the devId require updating all applications using it.\n- Ensure compliance with eBay's developer policies when using the devId.\n\n**Dependency chain**\n- Often used alongside appId and certId for full API authentication.\n- May be required before obtaining OAuth tokens or other credentials.\n- Linked to developer account settings and permissions on eBay.\n\n**Technical details**\n- Typically a string of alphanumeric characters.\n- Assigned by eBay upon developer registration.\n- Used in API request headers or query parameters depending on the API endpoint.\n- Validated by eBay servers to authorize API access."},"certId":{"type":"string","description":"The eBay certificate ID value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `certId_crypt`/`certId_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext certificate ID value here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"ruName":{"type":"string","description":"The Russian name associated with the eBay entity, typically used for localization and display purposes in Russian-language contexts. This field contains the name as it should appear to Russian-speaking users, ensuring proper representation and cultural relevance.\n\n**Field behavior**\n- Represents the localized name in Russian.\n- Used primarily for display in Russian language interfaces.\n- Should accurately reflect the entity's name in Russian script.\n- May be omitted if no Russian localization is available.\n\n**Implementation guidance**\n- Ensure the name is correctly translated and culturally appropriate.\n- Use Cyrillic characters as per Russian language standards.\n- Validate the string for encoding compatibility (UTF-8).\n- Update this field when the entity's Russian name changes.\n\n**Examples**\n- \"Электроника\" (Electronics)\n- \"Мода\" (Fashion)\n- \"Дом и сад\" (Home and Garden)\n\n**Important notes**\n- This field is optional if the entity does not have a Russian localization.\n- Avoid transliterations; use proper Russian language terms.\n- Consistency with other localized names is important for user experience.\n\n**Dependency chain**\n- May depend on the primary name or English name for context.\n- Used in conjunction with other localized name fields for multi-language support.\n\n**Technical details**\n- Data type: string.\n- Character encoding: UTF-8.\n- Maximum length should conform to system constraints for name fields."}},"description":"Contains configuration settings and credentials specific to eBay integration within the application. This property manages parameters required to connect, authenticate, and interact with eBay's APIs and services.\n\n**Field behavior**\n- Holds all necessary eBay-related configuration details.\n- Used to enable and customize eBay platform interactions.\n- May include API keys, tokens, endpoint URLs, and feature toggles.\n- Supports dynamic updates to eBay integration settings without redeploying the application.\n\n**Implementation guidance**\n- Securely store sensitive information such as API credentials.\n- Validate the presence and correctness of required fields before making API calls.\n- Support environment-specific configurations for different environments.\n- Ensure compatibility with the latest eBay API versions.\n- Provide clear error handling and logging for eBay-related operations.\n\n**Examples**\n- API key and secret for eBay developer account.\n- OAuth tokens for user authentication with eBay.\n- URLs for eBay REST or Trading API endpoints.\n- Flags to enable or disable specific eBay features like inventory management or order processing.\n\n**Important notes**\n- Credentials must be kept confidential and never exposed in client-side code.\n- Regularly update tokens and keys to maintain uninterrupted service.\n- Comply with eBay's API usage policies and rate limits.\n- Changes to this configuration may affect live eBay transactions and listings.\n\n**Dependency chain**\n- Dependent on eBay developer account and API access permissions.\n- Interacts with authentication modules to manage tokens.\n- Works alongside order management and inventory systems for synchronization.\n- May depend on network connectivity and proxy settings for API calls.\n\n**Technical details**\n- Typically structured as a nested object containing keys like clientId, clientSecret, accessToken, refreshToken, and apiEndpoints.\n- May include metadata such as token expiration timestamps and scopes.\n- Supports serialization and secure storage mechanisms.\n- Designed to be extensible for future eBay API features and versions."},"amazonmws":{"type":"object","properties":{"accessKeyId":{"type":"string","description":"The Access Key ID is a unique identifier assigned to your Amazon MWS (Marketplace Web Service) account, used to authenticate API requests. It acts as a public credential that, together with the Secret Access Key, allows secure access to Amazon MWS services. This key is essential for programmatic interaction with Amazon's seller APIs, enabling operations such as order retrieval, inventory management, and report generation.\n\n**Field behavior**\n- Must be a valid, active Access Key ID issued by Amazon.\n- Used in conjunction with the Secret Access Key to sign API requests.\n- Should be kept confidential to prevent unauthorized access.\n- Typically a 20-character alphanumeric string.\n\n**Implementation guidance**\n- Retrieve the Access Key ID from your AWS Management Console or Amazon MWS developer account.\n- Ensure the Access Key ID corresponds to the correct AWS user with appropriate permissions.\n- Do not hard-code the key in publicly accessible code repositories.\n- Rotate keys periodically to maintain security best practices.\n\n**Examples**\n- \"AKIAIOSFODNN7EXAMPLE\"\n- \"ABCD1234EFGH5678IJKL\"\n- \"A1B2C3D4E5F6G7H8I9J0\"\n\n**Important notes**\n- The Access Key ID alone is insufficient for authentication; it must be paired with the Secret Access Key.\n- Exposure of the Access Key ID and Secret Access Key can lead to unauthorized access and potential data breaches.\n- If compromised, immediately revoke and regenerate the keys via the AWS console.\n- Access Key IDs are case-sensitive.\n\n**Dependency chain**\n- Requires a corresponding Secret Access Key for request signing.\n- Must be associated with an AWS IAM user or role with Amazon MWS permissions.\n- Used alongside other credentials such as Seller ID and MWS Auth Token for full API access.\n\n**Technical details**\n- Format: 20-character alphanumeric string.\n- Used in the AWS Signature Version 2 or 4 signing process.\n- Included in the HTTP headers or query parameters of API requests.\n- Validated by Amazon MWS servers to authorize API calls."},"secretKey":{"type":"string","description":"The Amazon MWS secret key value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `secretKey_crypt`/`secretKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext secret key value here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."}},"description":"Configuration settings required to integrate with the Amazon Marketplace Web Service (Amazon MWS) API, enabling programmatic access to Amazon seller account data and operations. This includes credentials and parameters necessary for authentication, authorization, and interaction with various Amazon MWS endpoints.\n\n**Field behavior**\n- Contains all necessary authentication credentials such as Access Key ID, Secret Access Key, Seller ID, and MWS Auth Token.\n- May include configuration options like marketplace IDs, region settings, and API version.\n- Used to establish secure and authorized communication with Amazon MWS services.\n- Typically required for operations such as order retrieval, inventory management, and report generation.\n\n**Implementation guidance**\n- Ensure all credentials are stored securely and transmitted over encrypted channels.\n- Validate the presence and correctness of all required fields before attempting API calls.\n- Support refreshing or updating credentials as needed to maintain uninterrupted access.\n- Handle error responses gracefully, including authentication failures or permission issues.\n- Follow Amazon MWS best practices and rate limits to avoid throttling.\n\n**Examples**\n- Access Key ID: \"AKIAIOSFODNN7EXAMPLE\"\n- Secret Access Key: \"1234567890abcdef1234567890abcdef12345678\"\n- Seller ID: \"A1XEXAMPLE123\"\n- MWS Auth Token: \"amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE\"\n\n**Important notes**\n- Amazon MWS is being succeeded by the Selling Partner API (SP-API); consider migration plans.\n- Credentials must be kept confidential to prevent unauthorized access.\n- API access is subject to Amazon’s terms of service and usage policies.\n- Proper error handling is critical to manage API rate limits and service disruptions.\n\n**Dependency chain**\n- Requires valid Amazon seller account with MWS access enabled.\n- Dependent on network connectivity to Amazon MWS endpoints.\n- May depend on other configuration properties such as marketplace identifiers.\n\n**Technical details**\n- Uses RESTful API calls with XML or JSON payloads.\n- Authentication is based on AWS Signature Version 2 or 4.\n- Supports multiple API sections including Orders, Reports, Feeds, and Products.\n- Requires timestamp synchronization to prevent request rejection."},"jwt":{"type":"object","description":"A JSON Web Token (JWT) used for securely transmitting information between parties as a JSON object. This token is typically used for authentication and authorization purposes, ensuring that the client has valid credentials to access protected resources. The JWT contains encoded header, payload, and signature sections that verify the token's integrity and authenticity.\n**Field behavior**\n- Must be a valid JWT string following the standard format: header.payload.signature.\n- Used to authenticate API requests and authorize access to specific endpoints.\n- Typically included in the Authorization header as a Bearer token.\n- Should have an expiration time to enhance security.\n**Implementation guidance**\n- Validate the JWT on the server side to ensure it is properly signed and not expired.\n- Use secure algorithms (e.g., RS256 or HS256) for signing the token.\n- Store sensitive information in the payload with caution, as JWTs can be decoded by clients.\n- Refresh tokens should be used to obtain new JWTs when the current one expires.\n**Examples**\n- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\n- eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJleGFtcGxlLmNvbSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJleHAiOjE2MjQ2MjQwMDB9.DQABCD1234abcd5678efgh9012ijkl3456mnop7890qrstuv\n**Important notes**\n- JWTs should be transmitted over secure channels (HTTPS) to prevent interception.\n- Do not store JWTs in insecure storage locations on the client side (e.g., localStorage) to avoid XSS attacks.\n- Always verify the token's signature and claims before granting access.\n- Be aware of token expiration and implement proper handling for expired tokens.\n**Dependency chain**\n- Depends on the authentication mechanism generating the JWT.\n- Requires a"}}},"Response":{"type":"object","description":"Complete iClient object as returned by the API.\n\n**Note:** iClient responses do not include `createdAt`, `deletedAt`, or\n`_userId`. The only timestamp returned is `lastModified`.","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the iClient."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the last modification (ISO 8601, UTC)."},"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration instance ID (only present for integration-app iClients)."},"_connectorId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration app ID (only present for integration-app iClients)."}},"required":["_id"]}]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/iClients":{"post":{"summary":"Create an iClient","description":"Creates a new iClient configuration.\n","operationId":"createIClient","tags":["iClients"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"iClient created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}} ``` ## Get an iClient > Retrieves a specific iClient by its unique identifier.
```json {"openapi":"3.1.0","info":{"title":"iClients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Response":{"type":"object","description":"Complete iClient object as returned by the API.\n\n**Note:** iClient responses do not include `createdAt`, `deletedAt`, or\n`_userId`. The only timestamp returned is `lastModified`.","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the iClient."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the last modification (ISO 8601, UTC)."},"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration instance ID (only present for integration-app iClients)."},"_connectorId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration app ID (only present for integration-app iClients)."}},"required":["_id"]}]},"Request":{"type":"object","description":"Configuration for iclient","required":["provider"],"properties":{"_httpConnectorId":{"type":"string","format":"objectId","description":"Specifies the unique identifier for the HTTP connector used to establish network communication. This ID links the configuration to a specific HTTP connector instance, enabling the system to route requests appropriately.\n\n**Field behavior**\n- Accepts a string representing the connector's unique ID.\n- Used to reference an existing HTTP connector configuration.\n- Required when the operation depends on a specific HTTP connector.\n- Immutable once set during the lifecycle of the configuration.\n\n**Implementation guidance**\n- Ensure the ID corresponds to a valid and active HTTP connector within the system.\n- Validate the format of the ID to match expected patterns (e.g., UUID or predefined naming conventions).\n- Use this field to dynamically select or switch HTTP connectors in multi-connector environments.\n- Handle cases where the specified connector ID does not exist or is unavailable.\n\n**Examples**\n- \"connector-1234abcd\"\n- \"http-conn-5678efgh\"\n- \"uuid-550e8400-e29b-41d4-a716-446655440000\"\n\n**Important notes**\n- This field is critical for routing HTTP requests correctly.\n- Incorrect or missing connector IDs may lead to failed connections or errors.\n- The connector ID must be managed securely to prevent unauthorized access.\n\n**Dependency chain**\n- Depends on the existence of HTTP connector configurations within the system.\n- May influence or be influenced by authentication, proxy, or network settings tied to the connector.\n\n**Technical details**\n- Typically stored as a string data type.\n- May be used as a key in lookup tables or configuration maps.\n- Should be indexed for efficient retrieval in large-scale systems."},"_httpConnectorApiId":{"type":"string","format":"objectId","description":"Specifies the unique identifier of the HTTP Connector API associated with the current configuration or operation. This ID is used to reference and link the HTTP Connector API within the system, enabling seamless integration and communication between components.\n\n**Field behavior**\n- Acts as a reference pointer to a specific HTTP Connector API instance.\n- Must be a valid and existing API identifier within the system.\n- Used to establish connections and route requests appropriately.\n- Typically immutable once set to ensure consistent API linkage.\n\n**Implementation guidance**\n- Validate the ID against the list of available HTTP Connector APIs before assignment.\n- Ensure the ID format complies with the system’s identifier standards (e.g., UUID or specific naming conventions).\n- Handle cases where the referenced API ID does not exist or is deprecated.\n- Use this property to dynamically bind or switch HTTP Connector APIs in configurations.\n\n**Examples**\n- \"api-123e4567-e89b-12d3-a456-426614174000\"\n- \"http-connector-v2\"\n- \"connectorApi_987654321\"\n\n**Important notes**\n- This property is critical for routing HTTP requests correctly.\n- Incorrect or missing IDs can lead to failed API calls or misrouted traffic.\n- Changes to this ID should be managed carefully to avoid breaking integrations.\n- May require appropriate permissions to read or modify.\n\n**Dependency chain**\n- Depends on the existence of the HTTP Connector API registry or catalog.\n- Used by components responsible for HTTP request handling and routing.\n- May influence authentication, authorization, and logging mechanisms tied to the API.\n\n**Technical details**\n- Typically stored as a string data type.\n- Should be indexed for efficient lookup in large systems.\n- May be linked to metadata describing the HTTP Connector API’s capabilities and endpoints.\n- Often integrated with API management tools or service registries."},"enableIClientReferences":{"type":"boolean","description":"Determines whether the system should enable support for iClient references, allowing integration and interaction with iClient components or services. This setting controls the activation of features that facilitate communication, data exchange, or functionality extension through iClient references.\n\n**Field behavior**\n- When set to true, iClient references are enabled, allowing the system to recognize and process iClient-related interactions.\n- When set to false, iClient references are disabled, and any related functionality will be ignored or unavailable.\n- The field typically accepts a boolean value.\n\n**Implementation guidance**\n- Enable this setting only if your application requires integration with iClient components.\n- Ensure that enabling this does not conflict with other system configurations or security policies.\n- Validate the impact on performance and compatibility when toggling this setting.\n\n**Examples**\n- true: Enables iClient references, allowing the system to interact with iClient services.\n- false: Disables iClient references, preventing any iClient-related processing.\n\n**Important notes**\n- Enabling iClient references may require additional permissions or configurations on the client or server side.\n- Disabling this feature can improve security by limiting external references but may reduce functionality.\n- Changes to this setting might require a system restart or reinitialization to take effect.\n\n**Dependency chain**\n- May depend on the presence of iClient libraries or modules within the system.\n- Could be linked to authentication or authorization settings related to client references.\n- Might interact with other integration or communication-related configuration properties.\n\n**Technical details**\n- Typically implemented as a boolean flag in the configuration.\n- Controls conditional logic paths that handle iClient reference processing.\n- May influence API endpoints, middleware behavior, or client-server communication protocols."},"formType":{"type":"string","enum":["assistant","http"],"description":"Specifies which UI form is used to configure this iClient in integrator.io.\n\n**Critical:** How this is determined in the UI\n- If `_httpConnectorId` is set, the UI uses the **assistant** form.\n- If `_httpConnectorId` is not set, the UI uses the **http** form.\n\nThe **assistant** form is used for applications where integrator.io provides a guided setup assistant to make configuration easier.\n\n**Field behavior**\n- Controls the form layout and fields displayed in the UI.\n- May affect validation and conditional rendering in the UI.\n- Must be one of: `assistant`, `http`.\n\n**Implementation guidance**\n- Prefer letting the UI default this value based on `_httpConnectorId` unless you have a specific reason to override it.\n- Use `assistant` when configuring via an iClient assistant-backed application.\n- Use `http` for the standard HTTP configuration form.\n\n**Examples**\n- `assistant`\n- `http`\n\n**Important notes**\n- The value must be lowercase (`assistant` or `http`).\n- Changing this value impacts the UI experience for configuring the iClient.\n\n**Dependency chain**\n- Depends on whether the iClient is tied to an HTTP Connector (`_httpConnectorId`).\n- Influences which UI renderer is selected for the resource.\n\n**Technical details**\n- Stored as a lowercase string enum."},"settings":{"type":"object","description":"An object containing configuration options that customize the behavior and features of the system or application. This property allows users or developers to specify various parameters, preferences, and toggles that influence how the system operates, enabling flexible and dynamic adjustments to meet different requirements.\n\n**Field behavior**\n- Accepts a structured set of key-value pairs representing different configuration settings.\n- Can include nested objects to group related settings logically.\n- Modifications to this property typically affect system behavior immediately or upon the next initialization.\n- Supports enabling or disabling features, setting thresholds, defining modes, and other customizable options.\n\n**Implementation guidance**\n- Validate the structure and data types of the settings to ensure correctness.\n- Provide default values for unspecified settings to maintain predictable behavior.\n- Allow extensibility to accommodate future settings without breaking compatibility.\n- Document each configurable option clearly to guide users in setting appropriate values.\n\n**Examples**\n- Setting a timeout duration with `\"timeout\": 3000`.\n- Configuring logging levels with `\"logging\": {\"level\": \"verbose\", \"output\": \"file\"}`.\n- Toggling feature flags such as `\"features\": {\"betaAccess\": true, \"newUI\": false}`.\n\n**Important notes**\n- Changes to settings may require system restart or reinitialization to take effect.\n- Improper configuration can lead to unexpected behavior or degraded performance.\n- Sensitive settings should be protected and validated to prevent security risks.\n- The settings object should be kept as concise as possible to avoid complexity.\n\n**Dependency chain**\n- Dependent on the system's configuration management module.\n- May influence or be influenced by user preferences and environment variables.\n- Interacts with feature toggles, access controls, and runtime parameters.\n\n**Technical details**\n- Typically represented as a JSON object or equivalent data structure.\n- Supports various data types including strings, numbers, booleans, arrays, and nested objects.\n- May be stored in configuration files, databases, or managed via APIs.\n- Should support serialization and deserialization for persistence and transmission."},"settingsForm":{"type":"object","description":"An object representing the configuration and structure of a settings form used to capture user preferences or application parameters. This form typically includes fields, validation rules, default values, and UI metadata necessary for rendering and processing the settings interface.\n\n**Field behavior**\n- Defines the layout and components of the settings form.\n- Contains input fields with associated validation and default values.\n- Supports dynamic updates based on user interaction or external data.\n- Facilitates submission and retrieval of user-configured settings.\n\n**Implementation guidance**\n- Structure the form object to include field definitions, types, labels, and validation constraints.\n- Include metadata for UI rendering such as placeholders, tooltips, and grouping.\n- Ensure validation rules are comprehensive to prevent invalid input.\n- Support extensibility to add or modify fields without breaking existing functionality.\n\n**Examples**\n- A form object with fields for username, email preferences, and notification settings.\n- A nested form structure with sections for privacy, display, and account management.\n- Validation rules specifying required fields and acceptable value ranges.\n\n**Important notes**\n- The form should be designed to accommodate localization and accessibility standards.\n- Changes to the form structure may require corresponding updates in the UI and backend processing.\n- Ensure sensitive data fields are handled securely and comply with privacy regulations.\n\n**Dependency chain**\n- Depends on UI components to render the form fields.\n- Relies on validation logic to enforce input correctness.\n- Interacts with backend services to save and retrieve settings data.\n\n**Technical details**\n- Typically represented as a JSON object or similar structured data format.\n- May include nested objects or arrays to represent complex form hierarchies.\n- Validation rules can be expressed using standard schemas or custom logic.\n- Supports integration with form libraries or frameworks for rendering and state management."},"provider":{"type":"string","enum":["google","salesforce","azureoauth","windowslive","shopify","integrator","zendesk","bigcommerce","netsuite","ebay","ebay-xml","asana","box","dropbox","clover","servicenow","jobvite","twilio","certify","dropbox","squareup","docusign","woocommerce","microsoftbusinesscentral","custom_oauth2","amazonmws"],"description":"Specifies the **authentication provider/method** used by this iClient.\n\nThis value determines which authentication flow and credential fields are used (e.g., Google OAuth, Salesforce OAuth, NetSuite token-based auth, or a custom OAuth2 provider).\n\n**Field behavior**\n- Required.\n- Must be one of the supported provider enum values.\n- Drives the UI and validation rules for which authentication settings are shown/required.\n\n**Implementation guidance**\n- Pick the provider that matches the system you are authenticating against.\n- For generic OAuth2 providers, use `custom_oauth2`.\n- Ensure the corresponding auth configuration under `oauth2`, `jwt`, or provider-specific sections is populated as needed.\n\n**Examples**\n- google\n- salesforce\n- netsuite\n- custom_oauth2\n\n**Important notes**\n- This is not a human/vendor label — it is the provider key that selects an authentication method.\n\n**Dependency chain**\n- Influences which auth sub-configurations are applicable (for example, `oauth2.*`, `netsuite.*`, `salesforce.*`, `jwt.*`).\n\n**Technical details**\n- Stored as a lowercase string enum (see the `enum` list for allowed values)."},"name":{"type":"string"},"published":{"type":"boolean","description":"Indicates whether this iClient is published (available/visible for use).\n\n**Field behavior**\n- Boolean flag: `true` or `false`.\n- Used to control publication status in the UI.\n\n**Implementation guidance**\n- Default to `false` unless you intend to publish the iClient.\n\n**Examples**\n- `true`\n- `false`"},"enableJWT":{"type":"boolean","description":"Enables use of an additional **JWT assertion** as part of an OAuth authentication flow.\n\nUse this field when the OAuth provider requires a JWT assertion as a component of the OAuth specification. When enabled, you can use the Handlebars path `{{{iClient.jwt.token}}}` to obtain the JWT token value, which is then used in the **request body of the token URL** to generate an access token.\n\n**Field behavior**\n- When `true`, the iClient includes a JWT assertion/token as part of the OAuth token request.\n- When `false`, the OAuth flow does not incorporate a JWT assertion component.\n\n**Implementation guidance**\n- Enable only when your OAuth provider requires JWT assertion.\n- Populate the `jwt` configuration (e.g., `iClient.jwt.*`) so `{{{iClient.jwt.token}}}` can be resolved.\n- Use the resolved JWT token in the token request body parameters for the OAuth token URL, as required by the provider.\n\n**Examples**\n- `true` (OAuth token request includes a JWT assertion component)\n- `false` (standard OAuth flow without JWT assertion)\n\n**Important notes**\n- This flag is for **OAuth JWT assertion** use-cases; it does not mean “all requests must include a JWT Authorization header.”\n- If enabled without configuring `iClient.jwt`, token generation will fail.\n\n**Dependency chain**\n- Depends on `iClient.jwt` fields and the provider’s OAuth token request requirements.\n- Used when constructing the token URL request body for OAuth.\n\n**Technical details**\n- The JWT token can be referenced via `{{{iClient.jwt.token}}}` during request templating."},"netsuite":{"type":"object","properties":{"consumerKey":{"type":"string","description":"The NetSuite consumer key value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `consumerKey_crypt`/`consumerKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext consumer key here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"consumerSecret":{"type":"string","description":"The NetSuite consumer secret value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `consumerSecret_crypt`/`consumerSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext consumer secret here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."}},"description":"Configuration settings and credentials required to integrate with the NetSuite platform, enabling seamless data synchronization and interaction with NetSuite's ERP and CRM services. This property typically includes authentication details, API endpoints, and any necessary parameters for establishing a secure connection.\n\n**Field behavior**\n- Holds all necessary information to authenticate and communicate with NetSuite APIs.\n- Used to configure integration settings such as account ID, role, and environment.\n- Enables data exchange between the application and NetSuite for operations like record creation, updates, and queries.\n- May support multiple authentication methods, including token-based and OAuth.\n\n**Implementation guidance**\n- Ensure sensitive credentials are stored securely and encrypted.\n- Validate all required fields before attempting connection to NetSuite.\n- Support environment-specific configurations for different environments.\n- Handle error responses gracefully to maintain integration stability.\n- Keep the configuration up to date with NetSuite API version changes.\n\n**Examples**\n- API credentials including consumer key, consumer secret, token ID, and token secret.\n- Account ID and role ID for specifying the NetSuite account and user role.\n- URLs for NetSuite REST or SOAP API endpoints.\n- Flags or settings indicating the target environment.\n\n**Important notes**\n- Incorrect or outdated credentials will prevent successful integration.\n- NetSuite API limits and governance should be considered to avoid throttling.\n- Regularly review and rotate credentials to maintain security.\n- Integration may require specific permissions within NetSuite roles.\n\n**Dependency chain**\n- Dependent on secure storage mechanisms for credentials.\n- Relies on network connectivity to NetSuite services.\n- May depend on other configuration properties like logging or retry policies.\n\n**Technical details**\n- Typically includes OAuth 1.0a or token-based authentication parameters.\n- May require JSON or XML formatted configuration data.\n- Supports both REST and SOAP API protocols depending on use case.\n- Configuration format should align with NetSuite’s API specification requirements."},"oauth2":{"type":"object","properties":{"clientId":{"type":"string","description":"The unique identifier assigned to a client application during the OAuth 2.0 registration process. This client ID is used to identify the application when making authorization requests to the OAuth 2.0 authorization server. It is a public value that is included in authorization requests and token exchanges to associate the requests with the registered client.\n\n**Field behavior**\n- Must be a unique string assigned by the authorization server.\n- Used in authorization and token request flows to identify the client application.\n- Typically remains constant for the lifetime of the client registration.\n- Should be included in all OAuth 2.0 requests where client identification is required.\n\n**Implementation guidance**\n- Obtain the client ID from the OAuth 2.0 provider during client registration.\n- Store the client ID securely within the application configuration.\n- Do not treat the client ID as a secret; it can be exposed in URLs and logs.\n- Validate the client ID format according to the OAuth provider’s specifications.\n\n**Examples**\n- \"abc123xyz\"\n- \"myapp-client-001\"\n- \"1234567890abcdef\"\n\n**Important notes**\n- The client ID is distinct from the client secret; the latter must be kept confidential.\n- Exposure of the client ID does not compromise security but is necessary for proper OAuth flows.\n- Ensure the client ID matches exactly the value registered with the OAuth provider to avoid authentication errors.\n\n**Dependency chain**\n- Dependent on successful client registration with the OAuth 2.0 authorization server.\n- Used in conjunction with client secret (if applicable) during token requests.\n- Required for constructing authorization URLs and token exchange requests.\n\n**Technical details**\n- Typically a string of alphanumeric characters, sometimes including dashes or underscores.\n- May be case-sensitive depending on the OAuth provider.\n- Passed as a query parameter or in the request body during OAuth flows.\n- Must conform to the OAuth 2.0 specification and provider-specific requirements."},"clientSecret":{"type":"string","description":"The OAuth 2.0 **client secret** value.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this secret encrypted at rest (for example as `clientSecret_crypt` and `clientSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a secret is already set.\n\n**Implementation guidance**\n- Provide the plain client secret value here to set/update it.\n- To keep the existing secret unchanged during an update, omit this field (or, if the API/UI returns a masked value, keep `\"******\"` as-is)."},"scope":{"type":"array","items":{"type":"string"},"description":"OAuth 2.0 scopes requested for the access token.\n\n**API behavior:** the API accepts a string on input but always\nreturns an **array of strings** in responses. When you send a\nspace-delimited string like `\"openid profile\"`, the response\nwraps it as `[\"openid profile\"]`.\n\n**Examples**\n- `[]`\n- `[\"openid profile email\"]`\n- `[\"read\", \"write\"]`"},"scopeDelimiter":{"type":"string","description":"Specifies the character or string used to separate multiple OAuth2 scopes within a single authorization request or token. This delimiter enables the parsing and interpretation of scope values when they are provided as a concatenated string. Common delimiters include spaces, commas, or other characters depending on the OAuth2 provider's implementation.\n\n**Field behavior**\n- Defines how multiple scopes are split and recognized in authorization requests.\n- Ensures correct parsing of scope strings when multiple scopes are requested simultaneously.\n- Influences the format of the scope parameter in OAuth2 authorization URLs and tokens.\n\n**Implementation guidance**\n- Choose a delimiter that aligns with the OAuth2 provider's specification or defaults (e.g., space is standard per OAuth2 spec).\n- Ensure consistent use of the delimiter across all OAuth2 requests and responses.\n- Validate scope strings to correctly split and handle multiple scopes using this delimiter.\n- Document the chosen delimiter clearly for developers integrating with the API.\n\n**Examples**\n- Space character (\" \") as a delimiter: \"read write delete\"\n- Comma (\",\") as a delimiter: \"read,write,delete\"\n- Semicolon (\";\") as a delimiter: \"read;write;delete\"\n\n**Important notes**\n- The OAuth2 specification (RFC 6749) recommends using a space character as the scope delimiter.\n- Some OAuth2 providers may use non-standard delimiters; this property allows customization to accommodate those cases.\n- Incorrect delimiter configuration can lead to authorization failures or incorrect scope parsing.\n- When omitted, the default delimiter is typically a space character.\n\n**Dependency chain**\n- Depends on the OAuth2 authorization server's scope formatting requirements.\n- Influences how the 'scope' parameter in authorization requests and tokens is constructed and parsed.\n- May affect downstream components that interpret or validate scopes.\n\n**Technical details**\n- Typically a single character but can be a string if supported.\n- Used in string splitting functions to parse scope lists.\n- Should be URL-encoded if it is a special character in URLs.\n- Must be consistent with the OAuth2 provider's expectations to ensure interoperability."},"redirectUri":{"type":"string","description":"The URI to which the authorization server will redirect the user-agent after granting or denying access. This URI must be registered with the authorization server and should exactly match one of the pre-registered redirect URIs to prevent security vulnerabilities such as open redirect attacks. It is used in OAuth 2.0 authorization flows to receive authorization codes or access tokens securely.\n\n**Field behavior**\n- Specifies the callback endpoint for the authorization response.\n- Must be an absolute URI.\n- Used to return authorization codes or tokens after user consent.\n- Validated against pre-registered URIs to ensure security.\n\n**Implementation guidance**\n- Ensure the redirect URI is registered with the authorization server before use.\n- Use HTTPS to protect the integrity and confidentiality of the redirect.\n- Avoid using wildcard or overly broad redirect URIs.\n- Validate the redirect URI strictly on the server side to prevent open redirect vulnerabilities.\n\n**Examples**\n- https://client.example.com/callback\n- https://app.example.com/oauth2/callback\n- https://localhost:8080/auth/callback (for development purposes)\n\n**Important notes**\n- Mismatched redirect URIs will cause authorization requests to fail.\n- Redirect URIs should not contain fragments (#).\n- Avoid using query parameters unless necessary and registered.\n- The redirect URI is critical for security; improper configuration can lead to token leakage.\n\n**Dependency chain**\n- Depends on the authorization server's registered redirect URIs.\n- Used in conjunction with client_id and response_type parameters.\n- Integral to OAuth 2.0 authorization code and implicit grant flows.\n\n**Technical details**\n- Must conform to URI syntax as per RFC 3986.\n- Typically uses HTTPS scheme for security.\n- Should be URL-encoded when included in authorization requests.\n- The authorization server compares the redirect URI in the request with the registered URIs for exact match or pattern match depending on server policy."},"clientCredentialsLocation":{"type":"string","enum":["basicauthheader","body"],"description":"Specifies the location within the HTTP request where the client credentials (such as client ID and client secret) should be included when using the OAuth 2.0 client credentials grant type. This setting determines whether the credentials are sent in the request header (typically using the Authorization header with Basic authentication) or in the request body as form parameters.\n\n**Field behavior**\n- Defines where to place client credentials during the token request.\n- Accepts values indicating header or body placement.\n- Influences how the authentication server receives and validates client credentials.\n\n**Implementation guidance**\n- Use \"header\" to send credentials via the Authorization header using Basic authentication.\n- Use \"body\" to include credentials as form parameters in the POST request body.\n- Ensure compatibility with the OAuth 2.0 server’s expected credential location.\n- Validate that the chosen location aligns with security best practices and server requirements.\n\n**Examples**\n- \"header\" — client credentials sent in the Authorization header.\n- \"body\" — client credentials sent as form parameters in the request body.\n\n**Important notes**\n- Sending credentials in the header is generally preferred for security reasons.\n- Some OAuth 2.0 servers may only support one method; verify server documentation.\n- Incorrect configuration may lead to authentication failures.\n- Avoid exposing client credentials in URLs or query parameters.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 client credentials grant type being used.\n- Works in conjunction with clientId and clientSecret properties.\n- Affects the construction of the token request sent to the authorization server.\n\n**Technical details**\n- When set to \"header\", credentials are base64-encoded and included in the Authorization header.\n- When set to \"body\", credentials are included as \"client_id\" and \"client_secret\" form parameters.\n- Must comply with the OAuth 2.0 specification (RFC 6749) regarding client authentication methods."},"validDomainNames":{"type":"array","items":{"type":"string"},"description":"A list of domain names used to validate the OAuth URLs (Authorization, Access Token, Revoke Token).\n\nProvide each unique domain once (no scheme, no path).\n\n**Examples**\n- `[\"domain.com\"]`\n- `[\"domain.com\", \"domain1.com\", \"domain2.com\"]`\n\n**Technical details**\n- Stored as an array of strings."},"grantType":{"type":"string","enum":["authorizecode","password","clientcredentials"],"description":"Specifies the OAuth 2.0 grant type used to obtain an access token from the authorization server. This parameter determines the flow of the authentication process and how the client interacts with the authorization server to request and receive tokens. Common grant types include \"authorization_code\", \"client_credentials\", \"password\", and \"refresh_token\", each serving different use cases and security considerations.\n\n**Field behavior**\n- Defines the method by which the client application requests an access token.\n- Influences the parameters required in the token request.\n- Determines the security and user interaction model of the OAuth flow.\n- Must align with the authorization server's supported grant types.\n\n**Implementation guidance**\n- Choose the grant type based on the client application's capabilities and security requirements.\n- Ensure the authorization server supports the specified grant type.\n- Validate the grant type value against the OAuth 2.0 specification and any extensions used.\n- Handle errors gracefully if an unsupported or invalid grant type is provided.\n\n**Examples**\n- \"authorization_code\" for standard web server flows involving user authorization.\n- \"client_credentials\" for machine-to-machine authentication without user involvement.\n- \"password\" for legacy applications where the user provides credentials directly.\n- \"refresh_token\" to obtain a new access token using a previously issued refresh token.\n\n**Important notes**\n- Some grant types require additional parameters (e.g., \"authorization_code\" requires a code).\n- Using the \"password\" grant type is discouraged due to security risks.\n- The choice of grant type affects the overall security posture of the application.\n- Always use secure communication channels (HTTPS) when transmitting tokens and credentials.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 authorization server configuration.\n- Influences the required request parameters and token endpoint behavior.\n- Affects client registration details and scopes granted.\n\n**Technical details**\n- Must be a string matching one of the OAuth 2.0 defined grant types or extensions.\n- Sent as a parameter in the token request payload or URL-encoded form.\n- Case-sensitive and must conform to the OAuth 2.0 specification (RFC 6749).\n- May require additional headers or parameters depending on the grant type."},"failPath":{"type":"string","description":"Path to the **auth error field** in the HTTP response body.\n\nThis field only needs to be set if the API returns a field in the HTTP response body to indicate auth errors.\nFor example, if an API returns the field `errorMessage` with the value `Auth failed`, then set this field to `errorMessage`.\n\n**Examples**\n- `errorMessage`\n- `error`\n- `errors.0.message`"},"failValues":{"type":"array","items":{"type":"string"},"description":"Values to match against the HTTP response body field identified by\n`failPath`. If any value matches, the response is treated as an\nauth failure.\n\n**Examples**\n- `[\"access_denied\", \"invalid_grant\"]`\n- `[\"error\"]`"},"failStatusCode":{"type":"number","description":"HTTP status code that indicates an OAuth2 authentication error.\n\nThis field only needs to be set if the system you are authenticating against uses a status code **other than 401** for auth errors.\nFor example, an API may return a generic `400` status code, and then use a field in the HTTP response body to indicate authentication errors.\n\n**Field behavior**\n- Determines the HTTP response status code sent upon OAuth2 failure.\n- Influences client-side error handling and user feedback.\n- Overrides default failure status codes if explicitly set.\n\n**Implementation guidance**\n- Leave unset if auth errors are returned as `401` (default behavior).\n- Set this if auth failures are returned using another status code (e.g., `400`).\n\n**Examples**\n- 401\n- 400\n\n**Important notes**\n- Setting an inappropriate status code may lead to client confusion or security risks.\n- Some clients or intermediaries may behave differently depending on the status code.\n- The status code should be accompanied by a descriptive error message in the response body.\n\n**Dependency chain**\n- Depends on OAuth2 authentication and authorization failure events.\n- Works in conjunction with error response payloads and headers.\n- May interact with logging and monitoring systems for failure tracking.\n\n**Technical details**\n- Must be an integer within the range of valid HTTP status codes (100–599).\n- Typically used in HTTP response status line.\n- Should be consistent with OAuth2 error response standards defined in RFC 6749."},"useNewAuthFailSchema":{"type":"boolean","readOnly":true,"description":"Server-managed flag indicating whether the newer auth-failure\ndetection schema is in effect. Always `true` in current API\nresponses. Do not set this field in requests."},"failures":{"type":"array","readOnly":true,"description":"Server-computed summary of the auth-failure detection rules\nderived from `failPath`, `failValues`, and `failStatusCode`.\nPresent in responses only when those fields are configured.","items":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code that triggers auth-failure detection."},"path":{"type":"string","description":"Response body path checked for failure values."},"values":{"type":"array","items":{"type":"string"},"description":"Values at `path` that indicate an auth failure."}}}},"accessTokenLocation":{"type":"string","enum":["url","header","body"],"description":"Specifies the location where the OAuth 2.0 access token should be included when making API requests. This determines how the access token is transmitted to the server, such as in the HTTP header, query parameters, or request body. Proper configuration of this field ensures that the token is sent in a manner compatible with the API's authentication requirements.\n**Field behavior**\n- Defines the method of including the access token in API requests.\n- Common values include \"header\", \"query\", or \"body\".\n- Influences how the client constructs the request for authentication.\n**Implementation guidance**\n- Verify the API specification to determine the supported token locations.\n- Use \"header\" to include the token in the Authorization header (e.g., Bearer token).\n- Use \"query\" to append the token as a URL query parameter.\n- Use \"body\" to include the token within the request payload, typically for POST requests.\n- Ensure secure transmission, especially when using query parameters.\n**Examples**\n- \"header\" — Access token sent in the Authorization header.\n- \"query\" — Access token appended as ?access_token=XYZ in the URL.\n- \"body\" — Access token included in the POST request body parameters.\n**Important notes**\n- Sending tokens in query parameters can expose them in logs or browser history; use with caution.\n- The chosen location must align with the OAuth 2.0 server's expectations.\n- Some APIs may only support one method; incorrect configuration can lead to authentication failures.\n**Dependency chain**\n- Depends on the OAuth 2.0 flow and server requirements.\n- Works in conjunction with the access token value and token type.\n- Influences request construction and security considerations.\n**Technical details**\n- When set to \"header\", typically uses the \"Authorization: Bearer \" format.\n- When set to \"query\", appends the token as a URL parameter, often named \"access_token\".\n- When set to \"body\", includes the token in the request payload, usually as a form parameter.\n- Must be handled securely to prevent token leakage."},"accessTokenHeaderName":{"type":["string","null"],"description":"Header name used to send the OAuth 2.0 access token.\n\n**Examples**\n- `Authorization` (typically with value `Bearer `)\n- `X-Access-Token`"},"accessTokenPath":{"type":"string","description":"Specifies the relative URL path on the OAuth2 authorization server where the access token request should be sent. This path is appended to the base URL of the authorization server to form the full endpoint for obtaining an access token during the OAuth2 authentication flow. It is essential for enabling clients to exchange authorization grants for access tokens securely.\n\n**Field behavior**\n- Defines the endpoint path for access token requests in the OAuth2 flow.\n- Must be a valid relative URL path starting with a forward slash (/).\n- Used during the token exchange phase after obtaining an authorization code or other grant types.\n- Typically combined with the authorization server's base URL to form the complete token endpoint URL.\n\n**Implementation guidance**\n- Ensure the path corresponds exactly to the OAuth2 server's token endpoint specification.\n- Validate that the path is correctly formatted and accessible.\n- Avoid including query parameters or fragments in this path; it should be a clean URL path.\n- Confirm compatibility with the OAuth2 server's expected token endpoint URL structure.\n\n**Examples**\n- /oauth2/token\n- /api/v1/access_token\n- /auth/token\n\n**Important notes**\n- This path is critical for the OAuth2 token exchange process; incorrect configuration will prevent successful authentication.\n- It should not include the full URL, only the path component.\n- Must align with the OAuth2 server's documentation to ensure interoperability.\n- Often used in conjunction with other OAuth2 properties like client ID, client secret, and authorization path.\n\n**Dependency chain**\n- Depends on the base URL of the OAuth2 authorization server.\n- Used alongside authorizationPath and other OAuth2 configuration properties.\n- Integral to the OAuth2 token grant process.\n\n**Technical details**\n- Expected to be a URI path string.\n- Should begin with a forward slash (/).\n- Combined with the OAuth2 server's base URL to form the full token endpoint URI.\n- Utilized in HTTP POST requests to obtain access tokens."},"refreshTokenPath":{"type":"string","description":"The relative or absolute URL path used to request a refresh token from the OAuth 2.0 authorization server. This endpoint is typically called when the current access token has expired or is about to expire, allowing the client to obtain a new access token without requiring the user to re-authenticate. The path should conform to the OAuth 2.0 specification for token refresh requests and support the necessary HTTP methods, usually POST.\n\n**Field behavior**\n- Specifies the endpoint for refreshing OAuth 2.0 access tokens.\n- Used by the client application to maintain authenticated sessions seamlessly.\n- Invoked automatically by the client when the access token expires or is near expiration.\n- Must be accessible and correctly configured on the authorization server.\n\n**Implementation guidance**\n- Ensure the path is correctly formatted as a relative or absolute URL.\n- Confirm that the authorization server supports refresh token requests at this endpoint.\n- Secure the endpoint with appropriate authentication and authorization measures.\n- Validate that the client credentials and refresh token are correctly handled during the request.\n- Handle error responses gracefully, such as invalid or expired refresh tokens.\n\n**Examples**\n- \"/oauth2/token/refresh\"\n- \"https://auth.example.com/oauth2/token\"\n- \"/api/v1/auth/refresh-token\"\n\n**Important notes**\n- This path is distinct from the initial token request endpoint.\n- The refresh token flow requires that the client has previously obtained a refresh token.\n- Not all OAuth 2.0 providers support refresh tokens; verify compatibility.\n- The endpoint must support secure communication protocols (e.g., HTTPS).\n\n**Dependency chain**\n- Depends on the existence of a valid refresh token issued during initial authentication.\n- Works in conjunction with the access token and client credentials.\n- Related to the OAuth 2.0 token endpoint configuration.\n\n**Technical details**\n- Typically uses the HTTP POST method with form-encoded parameters.\n- Requires parameters such as grant_type=refresh_token and the refresh_token itself.\n- Responses include a new access token and optionally a new refresh token.\n- Must handle scopes and token expiration as per OAuth 2.0 standards."},"scheme":{"type":"string","description":"Specifies the OAuth 2.0 authorization scheme used for securing API requests. This field defines the method by which the client obtains and presents access tokens to authenticate and authorize API calls. Common schemes include \"authorization_code\", \"implicit\", \"password\", and \"client_credentials\", each representing a different OAuth 2.0 flow tailored to various client types and security requirements.\n\n**Field behavior**\n- Determines the OAuth 2.0 flow applied for token acquisition.\n- Influences how clients interact with the authorization server.\n- Guides the expected parameters and endpoints involved in the authentication process.\n\n**Implementation guidance**\n- Choose the scheme that best fits the client application type and security context.\n- Ensure the scheme aligns with the OAuth 2.0 specification and server capabilities.\n- Clearly document the chosen scheme to aid client developers in implementation.\n\n**Examples**\n- \"authorization_code\" for server-side web applications.\n- \"implicit\" for single-page applications.\n- \"password\" for trusted applications with user credentials.\n- \"client_credentials\" for machine-to-machine authentication.\n\n**Important notes**\n- Selecting an inappropriate scheme can lead to security vulnerabilities.\n- Some schemes may require additional parameters or configurations.\n- The scheme impacts token lifecycle and refresh mechanisms.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 specification version supported.\n- Interacts with token endpoint and authorization endpoint configurations.\n- Influences client registration and credential management.\n\n**Technical details**\n- Typically represented as a string value.\n- Must conform to recognized OAuth 2.0 flow identifiers.\n- Used by client libraries to determine authentication steps."},"accessTokenParamName":{"type":"string","description":"Parameter name used when the access token is passed as a query/body parameter (instead of a header).\n\n**Examples**\n- `access_token`\n- `token`\n- `auth_token`"},"useIClientFields":{"type":"boolean","description":"Determines whether to utilize the legacy iClient-specific fields in the OAuth2 configuration instead of the standard OAuth2 fields. This option is typically used for backward compatibility with systems or integrations that rely on the older iClient field structure.\n\n**Field behavior**\n- When set to true, the system uses iClient-specific OAuth2 fields for authentication.\n- When set to false or omitted, the system defaults to standard OAuth2 fields.\n- Influences how client credentials and tokens are processed during OAuth2 flows.\n\n**Implementation guidance**\n- Enable this flag only if integrating with legacy systems requiring iClient fields.\n- Ensure that the corresponding iClient fields are properly configured when this is enabled.\n- Validate compatibility with the OAuth2 provider before enabling this option.\n\n**Examples**\n- true: Use iClient-specific fields for OAuth2 authentication.\n- false: Use standard OAuth2 fields for authentication.\n\n**Important notes**\n- Enabling this may affect interoperability with modern OAuth2 providers.\n- This setting is primarily for backward compatibility and may be deprecated in future releases.\n- Misconfiguration can lead to authentication failures.\n\n**Dependency chain**\n- Depends on the presence of iClient-specific OAuth2 fields in the configuration.\n- Affects OAuth2 token request and refresh processes.\n\n**Technical details**\n- Overrides default OAuth2 client ID, secret, and token endpoint parameters with iClient equivalents.\n- May alter request payload structure during OAuth2 token exchanges.\n- Typically used in environments where legacy iClient authentication flows are required."},"pkceCodeChallengeMethod":{"type":["string","null"],"enum":["plain","s256"],"description":"PKCE code challenge method used for the OAuth 2.0 authorization code flow (RFC 7636).\n\n**Field behavior**\n- `s256` is recommended.\n- `plain` should only be used if required by the provider.\n\n**Examples**\n- `s256`\n- `plain`"},"auth":{"type":"object","properties":{"uri":{"type":"string","description":"The URI endpoint where the OAuth 2.0 authorization server accepts authorization requests. This URI is used by clients to initiate the authorization flow, typically by redirecting the resource owner's user-agent to this address. It must be a valid HTTPS URL to ensure secure transmission of sensitive information such as authorization codes or tokens.\n\n**Field behavior**\n- Serves as the entry point for the OAuth 2.0 authorization process.\n- Used by clients to request authorization from the resource owner.\n- Typically involves redirection of the user's browser to this URI.\n- Must support standard OAuth 2.0 authorization request parameters.\n\n**Implementation guidance**\n- Ensure the URI is an HTTPS endpoint to maintain security.\n- The endpoint should conform to OAuth 2.0 specifications for authorization endpoints.\n- Validate that the URI is reachable and correctly configured to handle authorization requests.\n- Include necessary query parameters as per OAuth 2.0 standards during requests.\n\n**Examples**\n- https://authorization-server.com/oauth2/authorize\n- https://accounts.example.com/auth\n- https://login.provider.com/oauth2/auth\n\n**Important notes**\n- The URI must be registered with the OAuth 2.0 provider and match the client configuration.\n- Using HTTP instead of HTTPS is not recommended due to security risks.\n- The URI should be stable and not change frequently to avoid client misconfigurations.\n- This endpoint is distinct from the token endpoint used to exchange authorization codes for tokens.\n\n**Dependency chain**\n- Dependent on the OAuth 2.0 client configuration specifying this URI.\n- Used in conjunction with client_id, redirect_uri, response_type, and scope parameters.\n- Works alongside the token endpoint URI for completing the OAuth flow.\n\n**Technical details**\n- Must be a valid, well-formed URL.\n- Should support GET requests with query parameters for authorization requests.\n- Typically responds with redirects (HTTP 302) to the redirect_uri with authorization codes or tokens.\n- Should implement security best practices such as TLS 1.2+ and proper CORS policies."}},"description":"Specifies the authentication method and credentials required for OAuth 2.0 authorization. This property defines how the client should authenticate with the authorization server to obtain an access token. It typically includes details such as client ID, client secret, token endpoint, scopes, and grant type.\n\n**Field behavior**\n- Determines the authentication flow used in the OAuth 2.0 process.\n- Controls how credentials are presented to the authorization server.\n- Influences token acquisition and refresh mechanisms.\n- May include multiple authentication parameters depending on the grant type.\n\n**Implementation guidance**\n- Ensure all required fields for the chosen OAuth 2.0 flow are included.\n- Securely store sensitive information like client secrets.\n- Validate the format and correctness of URLs and credentials.\n- Support common grant types such as authorization code, client credentials, and password.\n- Handle token expiration and refresh logic as needed.\n\n**Examples**\n- Client credentials flow with client ID and client secret.\n- Authorization code flow with redirect URI and scopes.\n- Password grant with username and password fields.\n- Refresh token usage for renewing access tokens.\n\n**Important notes**\n- Sensitive data must be protected and not exposed in logs or error messages.\n- The authentication method must comply with OAuth 2.0 standards.\n- Misconfiguration can lead to failed authentication or security vulnerabilities.\n- Different OAuth 2.0 providers may require specific parameters or formats.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 grant type specified elsewhere in the configuration.\n- Interacts with token endpoint URLs and scope definitions.\n- May be linked to client application registration details.\n\n**Technical details**\n- Typically includes fields such as client_id, client_secret, token_url, scopes, grant_type.\n- May require encoding or encryption of credentials during transmission.\n- Supports standard OAuth 2.0 token request and response formats.\n- Should handle HTTP status codes and error responses from the authorization server."},"token":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method used to call the OAuth 2.0 token endpoint.\n\n**Important notes**\n- `POST` is most common and recommended.\n- `GET` may expose sensitive data in URLs/logs."},"uri":{"type":"string","description":"The URI (Uniform Resource Identifier) specifying the endpoint where the OAuth 2.0 token request is sent to obtain an access token. This endpoint is responsible for authenticating the client and issuing tokens according to the OAuth 2.0 protocol. It must be a valid HTTPS URL to ensure secure transmission of sensitive credentials and tokens.\n\n**Field behavior**\n- Defines the exact URL to which token requests are made during the OAuth 2.0 flow.\n- Used by clients to exchange authorization grants or refresh tokens for access tokens.\n- Must support the OAuth 2.0 token request parameters and response formats.\n- Typically accessed via HTTP POST requests.\n\n**Implementation guidance**\n- Ensure the URI is a fully qualified HTTPS URL to maintain security.\n- Confirm the endpoint supports the OAuth 2.0 token exchange specification.\n- Validate the URI format before use to prevent runtime errors.\n- Document any additional headers or parameters required by the token endpoint.\n\n**Examples**\n- https://auth.example.com/oauth2/token\n- https://login.provider.com/oauth2/v1/token\n- https://api.service.com/oauth/token\n\n**Important notes**\n- The URI must be reachable and responsive to token requests.\n- Using HTTP instead of HTTPS is discouraged due to security risks.\n- The token endpoint may require client authentication via headers or request body.\n- Changes to this URI can disrupt the OAuth 2.0 authentication flow.\n\n**Dependency chain**\n- Dependent on the OAuth 2.0 authorization server configuration.\n- Used in conjunction with client credentials and grant types.\n- Related to other OAuth 2.0 endpoints such as authorization URI and revocation URI.\n\n**Technical details**\n- Must conform to URI syntax as per RFC 3986.\n- Typically accessed using HTTP POST with content type application/x-www-form-urlencoded.\n- Responses are usually JSON objects containing access tokens and metadata.\n- May support additional OAuth 2.0 extensions like PKCE or client authentication methods."},"body":{"type":"string","description":"The body property represents the payload content sent in the HTTP request when obtaining an OAuth 2.0 token. It typically includes key-value pairs such as grant type, client credentials, authorization code, refresh token, and scope, formatted according to the OAuth 2.0 specification. This property is essential for conveying the necessary parameters to the token endpoint to successfully authenticate and receive an access token.\n\n**Field behavior**\n- Contains the data sent in the HTTP request body during the token request.\n- Must include all required parameters based on the OAuth 2.0 grant type being used.\n- Often formatted as application/x-www-form-urlencoded or JSON, depending on the API requirements.\n- Is transmitted securely over HTTPS to protect sensitive information.\n\n**Implementation guidance**\n- Ensure the body includes all mandatory fields such as grant_type, client_id, client_secret, code, redirect_uri, or refresh_token as applicable.\n- Use the correct content type header matching the body format.\n- Encode parameters properly to comply with URL encoding standards if using form-urlencoded format.\n- Validate the body content before sending to avoid malformed requests.\n\n**Examples**\n- grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback&client_id=CLIENT_ID&client_secret=CLIENT_SECRET\n- { \"grant_type\": \"refresh_token\", \"refresh_token\": \"REFRESH_TOKEN\", \"client_id\": \"CLIENT_ID\" }\n\n**Important notes**\n- The exact parameters required in the body depend on the OAuth 2.0 flow implemented (authorization code, client credentials, password, refresh token).\n- Sensitive information such as client_secret should be handled securely and never exposed in logs or client-side code.\n- The body must conform to the OAuth 2.0 specification and the authorization server’s expectations.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 grant type selected.\n- Relies on correct client credentials and authorization codes obtained from prior steps.\n- Works in conjunction with HTTP headers like Content-Type and Authorization.\n\n**Technical details**\n- Typically sent as application/x-www-form-urlencoded or application/json.\n- Must be included in the POST request to the token endpoint URL.\n- Parameters are case-sensitive and must match the OAuth 2.0 specification.\n- The server response depends on the correctness and completeness of the body content."},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the token request when obtaining an OAuth 2.0 access token. These headers allow customization of the request, such as setting content types, authorization credentials, or custom metadata required by the token endpoint. The headers should be specified as key-value pairs where the key is the header name and the value is the header content.\n\n**Field behavior**\n- Overrides or supplements default headers sent in the token request.\n- Supports multiple headers to be included simultaneously.\n- Headers are sent exactly as specified without modification.\n- Used primarily during the OAuth 2.0 token exchange process.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized as per HTTP standards.\n- Avoid including sensitive information unless required and secure.\n- Validate header values to conform to expected formats (e.g., content-type).\n- Use this field to add custom headers required by specific OAuth providers.\n\n**Examples**\n- Authorization: Basic base64(client_id:client_secret)\n- Content-Type: application/x-www-form-urlencoded\n- Custom-Header: customValue\n\n**Important notes**\n- Headers specified here apply only to the token request, not to other OAuth flows.\n- Conflicts with default headers may cause token request failures.\n- Sensitive headers should be handled securely to prevent leaks.\n- Some OAuth providers may require specific headers for successful authentication.\n\n**Dependency chain**\n- Used in conjunction with oauth2.token.url and oauth2.token.body parameters.\n- May depend on client credentials or other authentication parameters.\n- Influences the HTTP request sent to the OAuth token endpoint.\n\n**Technical details**\n- Represented as a map/dictionary of string keys and string values.\n- Transmitted as HTTP headers in the token request POST or GET.\n- Supports standard HTTP header syntax and conventions.\n- Must comply with OAuth 2.0 token endpoint requirements and HTTP protocol."}},"description":"The access token issued by the OAuth 2.0 authorization server, used to authenticate and authorize API requests on behalf of the user or client. This token is typically a string representing a bearer token that must be included in the Authorization header of HTTP requests to access protected resources. It has a limited lifetime and scope, defining the permissions granted to the client.\n\n**Field behavior**\n- Represents the credential used to access protected resources.\n- Must be included in API requests to authenticate the client.\n- Has an expiration time after which it becomes invalid.\n- May be a JWT or opaque string depending on the authorization server.\n- Should be securely stored and transmitted only over HTTPS.\n\n**Implementation guidance**\n- Ensure the token is included in the Authorization header as \"Bearer {token}\".\n- Validate the token's expiration and scope before use.\n- Refresh the token using a refresh token if supported and expired.\n- Handle token revocation and errors gracefully.\n- Avoid logging or exposing the token in client-side code or URLs.\n\n**Examples**\n- \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n- \"2YotnFZFEjr1zCsicMWpAA\"\n- \"mF_9.B5f-4.1JqM\"\n\n**Important notes**\n- The token must be kept confidential to prevent unauthorized access.\n- Tokens are typically short-lived to enhance security.\n- Different APIs may require tokens with specific scopes or claims.\n- Always use secure transport (HTTPS) when transmitting tokens.\n\n**Dependency chain**\n- Obtained after successful OAuth 2.0 authorization or token exchange.\n- May depend on client credentials, authorization code, or refresh token.\n- Used in conjunction with the Authorization header in API requests.\n\n**Technical details**\n- Usually a string encoded in JWT or opaque format.\n- Contains claims or metadata about the user and permissions.\n- Includes an expiration timestamp (exp claim in JWT).\n- May include scopes defining access rights.\n- Must conform to OAuth 2.0 and OpenID Connect standards where applicable."},"refresh":{"type":"object","properties":{"body":{"type":"string","description":"The body of the HTTP request used to refresh an OAuth 2.0 access token. This typically includes parameters such as the refresh token, client credentials, grant type, and any additional required fields as specified by the OAuth 2.0 protocol. The body must be formatted according to the content type expected by the authorization server, commonly application/x-www-form-urlencoded.\n\n**Field behavior**\n- Contains all necessary parameters to request a new access token using a refresh token.\n- Must include the \"grant_type\" parameter set to \"refresh_token\".\n- Should include the \"refresh_token\" parameter with the valid refresh token value.\n- May include client authentication parameters such as \"client_id\" and \"client_secret\" if required.\n- Sent as the payload of the HTTP POST request to the token endpoint.\n\n**Implementation guidance**\n- Ensure the body is properly URL-encoded if using application/x-www-form-urlencoded content type.\n- Validate that all required parameters are present before sending the request.\n- Follow the OAuth 2.0 specification (RFC 6749) for the exact parameter names and values.\n- Handle any additional parameters required by the specific OAuth provider.\n- Securely handle sensitive information such as client secrets and refresh tokens.\n\n**Examples**\n- grant_type=refresh_token&refresh_token=xyz123&client_id=abc&client_secret=secret\n- grant_type=refresh_token&refresh_token=def456\n\n**Important notes**\n- The refresh token must be valid and not expired or revoked.\n- The authorization server may require client authentication in the body or via other means.\n- The content type header must match the format of the body (e.g., application/x-www-form-urlencoded).\n- Improper formatting or missing parameters will result in an error response from the server.\n\n**Dependency chain**\n- Depends on having a valid refresh token obtained from a previous authorization.\n- Requires knowledge of the OAuth 2.0 token endpoint URL.\n- May depend on client credentials if the server requires client authentication.\n- Relies on the correct grant_type parameter to indicate a refresh token request.\n\n**Technical details**\n- Typically sent as an HTTP POST request body.\n- Commonly uses application/x-www-form-urlencoded encoding.\n- Parameters include \"grant_type\", \"refresh_token\", and optionally \"client_id\" and \"client_secret\".\n- Must comply with OAuth 2.0 RFC 6749 Section 6 for token refresh requests."},"method":{"type":"string","enum":["GET","POST"],"description":"Specifies the HTTP method to be used when making the refresh token request in the OAuth 2.0 authentication flow. This method determines how the refresh token and related parameters are sent to the authorization server to obtain a new access token. Common HTTP methods include POST and GET, with POST being the most widely used due to its ability to securely transmit data in the request body.\n\n**Field behavior**\n- Defines the HTTP verb for the token refresh request.\n- Influences how parameters are encoded and transmitted.\n- Affects compatibility with different OAuth 2.0 server implementations.\n\n**Implementation guidance**\n- Typically set to POST for secure transmission of sensitive data.\n- Ensure the chosen method aligns with the OAuth 2.0 server’s requirements.\n- Validate that the client library or HTTP client supports the specified method.\n- Consider security implications of using GET, as parameters may be exposed in URLs.\n\n**Examples**\n- POST\n- GET\n\n**Important notes**\n- Using GET may expose refresh tokens in URLs, which can be logged or cached.\n- Some OAuth 2.0 servers may only support POST for token refresh requests.\n- The method must be consistent with the server’s expected protocol to avoid errors.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 server’s token endpoint configuration.\n- Interacts with the refresh token and client credentials parameters.\n- Influences the HTTP headers and body formatting of the request.\n\n**Technical details**\n- HTTP methods are case-insensitive but typically uppercase.\n- POST requests send parameters in the request body using application/x-www-form-urlencoded format.\n- GET requests send parameters as URL query parameters.\n- Proper handling of HTTP status codes and responses is required based on the method used."},"uri":{"type":"string","description":"Refresh token endpoint URI used to exchange a refresh token for a new access token (RFC 6749 Section 6).\n\n**Examples**\n- https://auth.example.com/oauth2/token\n- https://login.provider.com/oauth2/v1/token"},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the OAuth 2.0 refresh token request. These headers can be used to pass additional metadata, authentication information, or custom parameters required by the authorization server during the token refresh process. Typically, this may include headers such as `Content-Type`, `Authorization`, or any other custom headers mandated by the API specification.\n\n**Field behavior**\n- Accepts key-value pairs representing HTTP header names and their corresponding values.\n- Headers are included in the HTTP request sent to the token endpoint during the refresh token flow.\n- Overrides or supplements default headers set by the client or HTTP library.\n- Supports standard and custom headers as required by the OAuth 2.0 provider.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized and conform to HTTP standards.\n- Avoid including sensitive information in headers unless required and secured.\n- Validate header values to prevent injection or formatting errors.\n- Use this field to add headers like `Authorization` if the token endpoint requires client authentication via headers.\n- Do not duplicate headers that are automatically managed by the HTTP client unless overriding is necessary.\n\n**Examples**\n- `Content-Type: application/x-www-form-urlencoded`\n- `Authorization: Basic base64(client_id:client_secret)`\n- `Custom-Header: customValue`\n\n**Important notes**\n- Headers specified here apply only to the refresh token request, not to other OAuth 2.0 flows.\n- Misconfigured headers can cause token refresh failures or security issues.\n- Some OAuth 2.0 servers require specific headers for token refresh requests; consult the provider’s documentation.\n- Sensitive headers should be handled securely to prevent exposure.\n\n**Dependency chain**\n- Used in conjunction with `oauth2.refresh.tokenUrl` to make the refresh token request.\n- May depend on client authentication method specified elsewhere in the OAuth 2.0 configuration.\n- Interacts with HTTP client settings that manage default headers.\n\n**Technical details**\n- Represented as a map/dictionary of string keys and string values.\n- Translated into HTTP headers in the outgoing POST request to the token endpoint.\n- Must comply with HTTP/1.1 header field syntax and encoding rules.\n- Typically sent over HTTPS to ensure confidentiality and integrity."}},"description":"Indicates whether the OAuth2 refresh token flow is supported/enabled.\n\n**Examples**\n- `true`\n- `false`"},"revoke":{"type":"object","properties":{"uri":{"type":"string","description":"The URI endpoint where OAuth 2.0 token revocation requests are sent. This URI is used by clients to invalidate access or refresh tokens, ensuring they can no longer be used for authentication or authorization. It must be a valid HTTPS URL to guarantee secure transmission of sensitive token data.\n\n**Field behavior**\n- Accepts a single string value representing the revocation endpoint URL.\n- Used by clients to send HTTP POST requests to revoke tokens.\n- Should support standard OAuth 2.0 token revocation parameters as per RFC 7009.\n- Must be reachable and respond appropriately to revocation requests.\n\n**Implementation guidance**\n- Ensure the URI uses HTTPS to protect token data during transmission.\n- The endpoint should conform to OAuth 2.0 Token Revocation specification (RFC 7009).\n- Validate the URI format to prevent misconfiguration.\n- Document any additional headers or authentication required by the revocation endpoint.\n\n**Examples**\n- https://auth.example.com/oauth2/revoke\n- https://api.service.com/oauth2/token/revoke\n\n**Important notes**\n- The revocation URI is distinct from the authorization and token endpoints.\n- Proper implementation of token revocation enhances security by allowing clients to invalidate tokens when no longer needed.\n- Failure to provide a valid revocation URI may prevent clients from properly revoking tokens.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 authorization server configuration.\n- Related to the OAuth 2.0 token endpoint and authorization endpoint.\n- Used in conjunction with client credentials and tokens issued by the authorization server.\n\n**Technical details**\n- Typically accessed via HTTP POST with parameters such as token and token_type_hint.\n- Must handle authentication of the client making the revocation request.\n- Should return appropriate HTTP status codes indicating success or failure of revocation."},"body":{"type":"string","description":"The request body containing the parameters required to revoke an OAuth 2.0 token. This typically includes the token to be revoked and may also specify the token type hint to indicate whether the token is an access token or a refresh token. The body must be formatted according to the application/x-www-form-urlencoded MIME type as per the OAuth 2.0 Token Revocation specification (RFC 7009).\n\n**Field behavior**\n- Contains key-value pairs representing the token and optional token type hint.\n- Must be included in the HTTP POST request to the token revocation endpoint.\n- Parameters are URL-encoded in the request body.\n- Used to instruct the authorization server to invalidate a specific token.\n\n**Implementation guidance**\n- Ensure the body includes the \"token\" parameter with the token string to revoke.\n- Optionally include \"token_type_hint\" with values like \"access_token\" or \"refresh_token\" to assist the server.\n- Use application/x-www-form-urlencoded content type for the request.\n- Validate that the token parameter is present and correctly formatted before sending.\n- Handle server responses to confirm successful revocation or errors.\n\n**Examples**\n- token=SlAV32hkKG\n- token=34xkj23j4k23&token_type_hint=refresh_token\n- token=abcdef123456&token_type_hint=access_token\n\n**Important notes**\n- The token parameter is mandatory; omission will result in an error.\n- The token_type_hint is optional but recommended to improve server processing.\n- Revocation requests must be authenticated as per the authorization server’s requirements.\n- Revoking a token invalidates it immediately, preventing further use.\n- The body must not contain any additional parameters beyond those defined by the specification.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 token revocation endpoint being correctly configured.\n- Requires the client to have a valid token to revoke.\n- May depend on client authentication credentials included in the request headers.\n- The server’s response depends on the correctness of the body parameters.\n\n**Technical details**\n- Content-Type: application/x-www-form-urlencoded\n- Encoding: URL-encoded key-value pairs\n- Parameters:\n - token (string, required): The token to be revoked.\n - token_type_hint (string, optional): A hint about the type of the token.\n- HTTP Method: POST\n- Conforms to RFC 7009 (OAuth 2.0 Token Revocation)"},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the token revocation request for OAuth 2.0. These headers can be used to specify additional metadata such as content type, authorization credentials, custom client information, or any other required HTTP headers that the revocation endpoint expects. This allows for greater flexibility and control over the HTTP request sent to the authorization server when revoking tokens.\n\n**Field behavior**\n- Accepts key-value pairs representing HTTP header names and their corresponding values.\n- Headers are included in the HTTP request sent to the token revocation endpoint.\n- Can override default headers or add custom headers as needed.\n- Supports standard headers like `Authorization`, `Content-Type`, and custom headers.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized and conform to HTTP standards.\n- Avoid including sensitive information in headers unless required and secure.\n- Validate header values to prevent injection or formatting errors.\n- Use this field to comply with specific OAuth 2.0 server requirements for token revocation.\n\n**Examples**\n- `Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0`\n- `Content-Type: application/x-www-form-urlencoded`\n- `X-Custom-Header: customValue`\n\n**Important notes**\n- Headers specified here will be sent only during the token revocation request.\n- Misconfigured headers may cause the revocation request to fail.\n- This field does not affect other OAuth 2.0 requests such as token acquisition or introspection.\n\n**Dependency chain**\n- Used in conjunction with the `oauth2.revoke.url` property specifying the revocation endpoint.\n- May depend on `oauth2.revoke.method` to determine the HTTP method used.\n- Works alongside other OAuth 2.0 configuration properties to complete the revocation flow.\n\n**Technical details**\n- Represented as a map or dictionary of string key-value pairs.\n- Incorporated into the HTTP request headers when making the revocation call.\n- Must comply with HTTP header syntax and encoding rules.\n- Typically used in HTTP POST requests to the revocation endpoint."}},"description":"Indicates whether the OAuth2 token revocation endpoint is supported/enabled (RFC 7009).\n\n**Examples**\n- `true`\n- `false`"},"username":{"type":"string","description":"The username used to authenticate the user within the OAuth2 authorization framework. This value typically represents the unique identifier assigned to the user by the authentication provider or system. It is required when performing resource owner password credentials grant or other flows that involve direct user authentication.\n\n**Field behavior**\n- Must be a non-empty string representing the user's login identifier.\n- Used in conjunction with the password to obtain an access token.\n- Should be case-sensitive depending on the authentication system.\n- Validated against the authentication provider's user database.\n\n**Implementation guidance**\n- Ensure the username is securely transmitted over HTTPS to protect user credentials.\n- Validate the format and existence of the username before processing authentication.\n- Avoid logging the username in plain text to maintain user privacy.\n- Support international characters if the authentication system allows.\n\n**Examples**\n- \"johndoe\"\n- \"user@example.com\"\n- \"alice123\"\n\n**Important notes**\n- The username must correspond to a valid user account in the OAuth2 provider.\n- Incorrect usernames will result in authentication failure.\n- Should be handled securely to prevent exposure of sensitive user information.\n\n**Dependency chain**\n- Typically used alongside the `password` property in OAuth2 password grant flows.\n- Dependent on the OAuth2 server's user management and authentication mechanisms.\n\n**Technical details**\n- Data type: string\n- Maximum length may vary depending on the OAuth2 provider.\n- Should be URL-encoded if included in query parameters or request bodies."},"password":{"type":"string","description":"The OAuth2 **password** value (used with the password grant).\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores the password encrypted at rest (for example as `password_crypt`/`password_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a password is already set.\n\n**Implementation guidance**\n- Provide the plain password value here to set/update it.\n- To keep the existing password unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"unencrypted":{"type":"object","description":"Store all **non-sensitive** fields required by your imports and exports to access the app you are connecting to.\n\nThese values can be referenced by resources within integrator.io through the iClient.\n\n**Examples**\n- `{\"email\":\"my_email@company.com\", \"accountId\": \"8675301\", \"role\":\"admin\"}`\n\n**Important notes**\n- Only store non-sensitive values here (safe to store unencrypted).\n- Use `encrypted` for secrets (passwords, tokens, keys)."},"encrypted":{"type":"object","description":"Store all **sensitive** fields required by your imports and exports to access the app you are connecting to.\n\nThese values are stored with **AES-256 encryption** and other layers of protection to keep your data safe.\nThese values can be referenced by resources within integrator.io through the iClient.\n\n**Examples**\n- `{\"password\":\"celigorocks\"}`\n- `{\"token\":\"x7if4nkovhgr63ghp\"}`\n\n**Important notes**\n- Use this for secrets (passwords, tokens, keys).\n- Values may be masked (e.g., `\"******\"`) in API responses once stored."}},"description":"Configuration settings for OAuth 2.0 authentication, enabling secure authorization and access delegation for API clients. This property typically includes details such as authorization URLs, token URLs, scopes, client credentials, and grant types supported by the OAuth 2.0 provider.\n\n**Field behavior**\n- Defines the OAuth 2.0 flow and parameters required for client authentication.\n- Specifies the endpoints for obtaining authorization and access tokens.\n- Lists the scopes that determine the level of access granted.\n- Supports multiple OAuth 2.0 grant types (e.g., authorization code, client credentials).\n- Enables secure token exchange and refresh mechanisms.\n\n**Implementation guidance**\n- Ensure URLs for authorization and token endpoints are accurate and reachable.\n- Clearly define the scopes to limit access according to least privilege principles.\n- Include client ID and client secret securely, avoiding exposure in client-side code.\n- Support refresh tokens if long-lived sessions are required.\n- Validate tokens on the server side to maintain security.\n\n**Examples**\n- Authorization code flow with authorization URL, token URL, and scopes.\n- Client credentials flow with token URL and client credentials.\n- Implicit flow configuration for single-page applications.\n- Refresh token configuration for renewing access tokens.\n\n**Important notes**\n- OAuth 2.0 configurations must comply with the security best practices to prevent token leakage.\n- Sensitive information such as client secrets should never be exposed publicly.\n- The choice of grant type depends on the client application type and security requirements.\n- Proper error handling should be implemented for token acquisition failures.\n\n**Dependency chain**\n- Depends on the presence of an OAuth 2.0 compliant authorization server.\n- Requires secure storage and transmission of client credentials.\n- Interacts with API endpoints that enforce OAuth 2.0 token validation.\n\n**Technical details**\n- Typically includes fields like authorizationUrl, tokenUrl, refreshUrl, scopes, clientId, clientSecret, and grantTypes.\n- Uses HTTPS endpoints to ensure secure communication.\n- May support PKCE (Proof Key for Code Exchange) for enhanced security in public clients.\n- Tokens are usually JWTs or opaque tokens depending on the OAuth provider implementation."},"salesforce":{"type":"object","properties":{"clientId":{"type":"string","description":"The unique identifier assigned to a client application by Salesforce during the OAuth client registration process. This ID is used to authenticate the client when making API requests and establishing a secure connection with Salesforce services. It is essential for enabling authorized access to Salesforce resources on behalf of the client application.\n**Field behavior**\n- Must be a non-empty string.\n- Used as part of the OAuth authentication flow.\n- Typically remains constant for a given client application.\n- Required for initiating API calls to Salesforce.\n**Implementation guidance**\n- Obtain this value from the Salesforce connected app configuration.\n- Store securely and avoid exposing it in client-side code.\n- Validate the format to ensure it matches Salesforce client ID patterns.\n- Use in conjunction with clientSecret for authentication.\n**Examples**\n- \"3MVG9d6T2QxX9z5l7Y8P0qR1sT2uVwXyZAbCdEfGhIjKlMnOpQrStUvWxYz123456\"\n- \"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\"\n**Important notes**\n- The clientId alone does not grant access; it must be paired with appropriate credentials and tokens.\n- Changing the clientId requires updating all integrations using it.\n- Keep the clientId confidential to prevent unauthorized access.\n**Dependency chain**\n- Dependent on the Salesforce connected app setup.\n- Works alongside clientSecret, redirectUri, and OAuth tokens.\n- Required for generating access tokens.\n**Technical details**\n- Typically a 40-character alphanumeric string.\n- Assigned by Salesforce upon connected app creation.\n- Used in HTTP headers or request parameters during OAuth flows."},"clientSecret":{"type":"string","description":"The Salesforce OAuth **client secret** value.\n\nThis is the value you provide to configure or update the Salesforce iClient. Internally, integrator.io stores this secret encrypted at rest (for example as `clientSecret_crypt` and `clientSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a secret is already set.\n\n**Implementation guidance**\n- Provide the plain client secret value here to set/update it.\n- To keep the existing secret unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"apiToken":{"type":"string","description":"The API token used to authenticate requests to the Salesforce API. This token acts as a secure credential that grants access to Salesforce resources and operations, ensuring that only authorized clients can interact with the Salesforce environment. It is typically generated within Salesforce or through an OAuth flow and must be kept confidential to prevent unauthorized access.\n\n**Field behavior**\n- Used for authenticating API calls to Salesforce.\n- Must be included in the authorization header or as specified by the Salesforce API.\n- Typically has an expiration time and may require periodic renewal.\n- Invalid or expired tokens will result in authentication errors.\n\n**Implementation guidance**\n- Store the token securely, such as in environment variables or secure vaults.\n- Avoid hardcoding the token in source code or exposing it in logs.\n- Implement token refresh logic if using OAuth tokens with limited lifespans.\n- Validate the token format before use to prevent malformed requests.\n\n**Examples**\n- A long alphanumeric string like \"00Dxx0000001gPFEAY!AQ0AQJ...\"\n- OAuth access tokens obtained via Salesforce OAuth 2.0 flows.\n- Tokens generated from Salesforce connected apps for API access.\n\n**Important notes**\n- The API token is sensitive information and should be treated like a password.\n- Sharing or leaking the token can compromise Salesforce data security.\n- Ensure compliance with Salesforce security policies when handling tokens.\n- Different Salesforce environments (non-production vs production) may require different tokens.\n\n**Dependency chain**\n- Dependent on Salesforce user credentials or OAuth authorization flows.\n- Used in conjunction with the Salesforce instance URL and API endpoints.\n- May require additional headers or parameters as per Salesforce API specifications.\n\n**Technical details**\n- Typically included in HTTP headers as \"Authorization: Bearer {apiToken}\".\n- May have scopes or permissions associated depending on how it was generated.\n- Tokens may be JWTs or opaque strings depending on the authentication method.\n- Salesforce APIs validate the token on each request to authorize access."},"privateKey":{"type":"string","description":"The Salesforce private key value used for authentication flows such as JWT bearer token OAuth.\n\nThis is the value you provide to configure or update the Salesforce iClient. Internally, integrator.io stores this key encrypted at rest (for example as `privateKey_crypt`/`privateKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a key is already set.\n\n**Implementation guidance**\n- Provide the plaintext private key value here to set/update it (often PEM formatted).\n- To keep the existing private key unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"publicKey":{"type":"string","description":"The publicKey property represents the public cryptographic key used for secure data encryption, verification, or authentication processes within the Salesforce integration. This key is typically part of a public-private key pair and is used to encrypt data or verify digital signatures without exposing the private key. It ensures secure communication and data integrity between systems.\n\n**Field behavior**\n- Accepts a string value representing the public key in a standard format (e.g., PEM, DER).\n- Used to encrypt data or verify signatures in cryptographic operations.\n- Must be provided in a format compatible with the consuming system.\n- Immutable once set for a given integration instance to maintain security.\n\n**Implementation guidance**\n- Ensure the public key is generated using a secure and recognized cryptographic algorithm (e.g., RSA, ECDSA).\n- Validate the key format before accepting it to prevent errors during cryptographic operations.\n- Store the key securely and restrict access to prevent unauthorized modifications.\n- Update the key only through a controlled process to avoid breaking integrations.\n\n**Examples**\n- A PEM-encoded RSA public key string starting with \"-----BEGIN PUBLIC KEY-----\".\n- An ECDSA public key represented in base64 encoding.\n- A public key string used to verify JWT tokens issued by Salesforce.\n\n**Important notes**\n- The publicKey must correspond to the private key held securely by the entity performing signing or decryption.\n- Do not expose the private key in any API or configuration.\n- Incorrect or malformed keys will cause authentication or encryption failures.\n- Keep the key updated in case of key rotation policies.\n\n**Dependency chain**\n- Dependent on the cryptographic algorithm and key pair generation process.\n- Used by authentication, encryption, or signature verification components.\n- May be linked to other security configurations such as certificates or token validation settings.\n\n**Technical details**\n- Typically encoded in PEM or DER format.\n- May include metadata such as key type and length.\n- Should comply with relevant security standards (e.g., PKCS#1, X.509).\n- Size and algorithm choice affect security strength and performance."}},"description":"Configuration settings and credentials required to integrate with Salesforce, enabling seamless data synchronization and interaction with Salesforce APIs. This property typically includes authentication details, API endpoints, and any necessary parameters for establishing a secure connection to a Salesforce instance.\n\n**Field behavior**\n- Holds all necessary information to authenticate and communicate with Salesforce services.\n- Used to configure API calls for data retrieval, updates, and other Salesforce operations.\n- May include nested objects or fields such as client ID, client secret, access tokens, instance URLs, and API versions.\n\n**Implementation guidance**\n- Ensure sensitive information like client secrets and access tokens are securely stored and transmitted.\n- Validate the presence and correctness of required fields before attempting Salesforce integration.\n- Support token refresh mechanisms if applicable to maintain session validity.\n- Allow configuration flexibility to support different Salesforce environments (e.g., non-production, production).\n\n**Examples**\n- An object containing OAuth credentials: client_id, client_secret, refresh_token, and instance_url.\n- Configuration specifying API version and endpoint URLs.\n- JSON structure with nested authentication and connection parameters.\n\n**Important notes**\n- Proper error handling should be implemented for authentication failures or API call errors.\n- Salesforce API limits and quotas should be considered when designing integration logic.\n- Secure handling of credentials is critical to prevent unauthorized access.\n- The structure and required fields may vary depending on the Salesforce API version and authentication method used.\n\n**Dependency chain**\n- Dependent on Salesforce authentication mechanisms (OAuth 2.0, username-password flow, etc.).\n- Relies on network connectivity to Salesforce endpoints.\n- May depend on external libraries or SDKs for Salesforce API interaction.\n\n**Technical details**\n- Typically involves OAuth 2.0 tokens or username-password credentials.\n- Uses HTTPS for secure communication with Salesforce REST or SOAP APIs.\n- May include refresh token logic to maintain long-term access.\n- Supports configuration of API versioning to align with Salesforce API changes."},"ebay":{"type":"object","properties":{"appId":{"type":"string","description":"The unique identifier assigned to an application registered with the eBay developer program. This ID is used to authenticate API requests and associate them with a specific application.\n\n**Field behavior**\n- Must be included in API requests to identify the calling application.\n- Typically a string consisting of alphanumeric characters.\n- Used to track usage and enforce rate limits for the application.\n- Required for accessing most eBay APIs.\n\n**Implementation guidance**\n- Obtain the appId by registering your application on the eBay Developer Program portal.\n- Keep the appId confidential to prevent unauthorized use.\n- Include the appId in the request headers or parameters as specified by the API documentation.\n- Validate the appId format before sending requests to avoid errors.\n\n**Examples**\n- \"12345678-1234-1234-1234-123456789abc\"\n- \"MyEbayAppID2024\"\n- \"APP-9876543210\"\n\n**Important notes**\n- The appId is different from other eBay credentials such as client ID or client secret.\n- Using an invalid or expired appId will result in authentication errors.\n- Do not share your appId publicly to protect your application's security.\n\n**Dependency chain**\n- Depends on successful registration with the eBay Developer Program.\n- Used in conjunction with other authentication credentials like OAuth tokens.\n- Required before making authorized API calls.\n\n**Technical details**\n- Typically a UUID or a unique string assigned by eBay.\n- Passed as part of HTTP headers or query parameters depending on the API.\n- Used by eBay servers to identify and authenticate the application making the request."},"devId":{"type":"string","description":"The unique identifier assigned to a developer or development team by eBay. This ID is used to authenticate and track API usage associated with the developer's applications. It ensures that API requests are properly attributed and helps manage access permissions and rate limits.\n\n**Field behavior**\n- Must be included in API requests requiring developer authentication.\n- Used to identify the source of API calls.\n- Typically remains constant for a given developer or development team.\n- Should be kept confidential to prevent unauthorized use.\n\n**Implementation guidance**\n- Obtain the devId by registering as a developer on the eBay Developer Program portal.\n- Include the devId in all relevant API request headers or parameters as specified by eBay.\n- Store the devId securely in your application environment.\n- Do not expose the devId in client-side code or public repositories.\n\n**Examples**\n- \"1234567890\"\n- \"dev_abcdef123456\"\n- \"9876543210\"\n\n**Important notes**\n- The devId is distinct from other eBay identifiers such as appId, certId, or auth tokens.\n- Misuse or leakage of the devId can lead to unauthorized API access.\n- Changes to the devId require updating all applications using it.\n- Ensure compliance with eBay's developer policies when using the devId.\n\n**Dependency chain**\n- Often used alongside appId and certId for full API authentication.\n- May be required before obtaining OAuth tokens or other credentials.\n- Linked to developer account settings and permissions on eBay.\n\n**Technical details**\n- Typically a string of alphanumeric characters.\n- Assigned by eBay upon developer registration.\n- Used in API request headers or query parameters depending on the API endpoint.\n- Validated by eBay servers to authorize API access."},"certId":{"type":"string","description":"The eBay certificate ID value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `certId_crypt`/`certId_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext certificate ID value here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"ruName":{"type":"string","description":"The Russian name associated with the eBay entity, typically used for localization and display purposes in Russian-language contexts. This field contains the name as it should appear to Russian-speaking users, ensuring proper representation and cultural relevance.\n\n**Field behavior**\n- Represents the localized name in Russian.\n- Used primarily for display in Russian language interfaces.\n- Should accurately reflect the entity's name in Russian script.\n- May be omitted if no Russian localization is available.\n\n**Implementation guidance**\n- Ensure the name is correctly translated and culturally appropriate.\n- Use Cyrillic characters as per Russian language standards.\n- Validate the string for encoding compatibility (UTF-8).\n- Update this field when the entity's Russian name changes.\n\n**Examples**\n- \"Электроника\" (Electronics)\n- \"Мода\" (Fashion)\n- \"Дом и сад\" (Home and Garden)\n\n**Important notes**\n- This field is optional if the entity does not have a Russian localization.\n- Avoid transliterations; use proper Russian language terms.\n- Consistency with other localized names is important for user experience.\n\n**Dependency chain**\n- May depend on the primary name or English name for context.\n- Used in conjunction with other localized name fields for multi-language support.\n\n**Technical details**\n- Data type: string.\n- Character encoding: UTF-8.\n- Maximum length should conform to system constraints for name fields."}},"description":"Contains configuration settings and credentials specific to eBay integration within the application. This property manages parameters required to connect, authenticate, and interact with eBay's APIs and services.\n\n**Field behavior**\n- Holds all necessary eBay-related configuration details.\n- Used to enable and customize eBay platform interactions.\n- May include API keys, tokens, endpoint URLs, and feature toggles.\n- Supports dynamic updates to eBay integration settings without redeploying the application.\n\n**Implementation guidance**\n- Securely store sensitive information such as API credentials.\n- Validate the presence and correctness of required fields before making API calls.\n- Support environment-specific configurations for different environments.\n- Ensure compatibility with the latest eBay API versions.\n- Provide clear error handling and logging for eBay-related operations.\n\n**Examples**\n- API key and secret for eBay developer account.\n- OAuth tokens for user authentication with eBay.\n- URLs for eBay REST or Trading API endpoints.\n- Flags to enable or disable specific eBay features like inventory management or order processing.\n\n**Important notes**\n- Credentials must be kept confidential and never exposed in client-side code.\n- Regularly update tokens and keys to maintain uninterrupted service.\n- Comply with eBay's API usage policies and rate limits.\n- Changes to this configuration may affect live eBay transactions and listings.\n\n**Dependency chain**\n- Dependent on eBay developer account and API access permissions.\n- Interacts with authentication modules to manage tokens.\n- Works alongside order management and inventory systems for synchronization.\n- May depend on network connectivity and proxy settings for API calls.\n\n**Technical details**\n- Typically structured as a nested object containing keys like clientId, clientSecret, accessToken, refreshToken, and apiEndpoints.\n- May include metadata such as token expiration timestamps and scopes.\n- Supports serialization and secure storage mechanisms.\n- Designed to be extensible for future eBay API features and versions."},"amazonmws":{"type":"object","properties":{"accessKeyId":{"type":"string","description":"The Access Key ID is a unique identifier assigned to your Amazon MWS (Marketplace Web Service) account, used to authenticate API requests. It acts as a public credential that, together with the Secret Access Key, allows secure access to Amazon MWS services. This key is essential for programmatic interaction with Amazon's seller APIs, enabling operations such as order retrieval, inventory management, and report generation.\n\n**Field behavior**\n- Must be a valid, active Access Key ID issued by Amazon.\n- Used in conjunction with the Secret Access Key to sign API requests.\n- Should be kept confidential to prevent unauthorized access.\n- Typically a 20-character alphanumeric string.\n\n**Implementation guidance**\n- Retrieve the Access Key ID from your AWS Management Console or Amazon MWS developer account.\n- Ensure the Access Key ID corresponds to the correct AWS user with appropriate permissions.\n- Do not hard-code the key in publicly accessible code repositories.\n- Rotate keys periodically to maintain security best practices.\n\n**Examples**\n- \"AKIAIOSFODNN7EXAMPLE\"\n- \"ABCD1234EFGH5678IJKL\"\n- \"A1B2C3D4E5F6G7H8I9J0\"\n\n**Important notes**\n- The Access Key ID alone is insufficient for authentication; it must be paired with the Secret Access Key.\n- Exposure of the Access Key ID and Secret Access Key can lead to unauthorized access and potential data breaches.\n- If compromised, immediately revoke and regenerate the keys via the AWS console.\n- Access Key IDs are case-sensitive.\n\n**Dependency chain**\n- Requires a corresponding Secret Access Key for request signing.\n- Must be associated with an AWS IAM user or role with Amazon MWS permissions.\n- Used alongside other credentials such as Seller ID and MWS Auth Token for full API access.\n\n**Technical details**\n- Format: 20-character alphanumeric string.\n- Used in the AWS Signature Version 2 or 4 signing process.\n- Included in the HTTP headers or query parameters of API requests.\n- Validated by Amazon MWS servers to authorize API calls."},"secretKey":{"type":"string","description":"The Amazon MWS secret key value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `secretKey_crypt`/`secretKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext secret key value here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."}},"description":"Configuration settings required to integrate with the Amazon Marketplace Web Service (Amazon MWS) API, enabling programmatic access to Amazon seller account data and operations. This includes credentials and parameters necessary for authentication, authorization, and interaction with various Amazon MWS endpoints.\n\n**Field behavior**\n- Contains all necessary authentication credentials such as Access Key ID, Secret Access Key, Seller ID, and MWS Auth Token.\n- May include configuration options like marketplace IDs, region settings, and API version.\n- Used to establish secure and authorized communication with Amazon MWS services.\n- Typically required for operations such as order retrieval, inventory management, and report generation.\n\n**Implementation guidance**\n- Ensure all credentials are stored securely and transmitted over encrypted channels.\n- Validate the presence and correctness of all required fields before attempting API calls.\n- Support refreshing or updating credentials as needed to maintain uninterrupted access.\n- Handle error responses gracefully, including authentication failures or permission issues.\n- Follow Amazon MWS best practices and rate limits to avoid throttling.\n\n**Examples**\n- Access Key ID: \"AKIAIOSFODNN7EXAMPLE\"\n- Secret Access Key: \"1234567890abcdef1234567890abcdef12345678\"\n- Seller ID: \"A1XEXAMPLE123\"\n- MWS Auth Token: \"amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE\"\n\n**Important notes**\n- Amazon MWS is being succeeded by the Selling Partner API (SP-API); consider migration plans.\n- Credentials must be kept confidential to prevent unauthorized access.\n- API access is subject to Amazon’s terms of service and usage policies.\n- Proper error handling is critical to manage API rate limits and service disruptions.\n\n**Dependency chain**\n- Requires valid Amazon seller account with MWS access enabled.\n- Dependent on network connectivity to Amazon MWS endpoints.\n- May depend on other configuration properties such as marketplace identifiers.\n\n**Technical details**\n- Uses RESTful API calls with XML or JSON payloads.\n- Authentication is based on AWS Signature Version 2 or 4.\n- Supports multiple API sections including Orders, Reports, Feeds, and Products.\n- Requires timestamp synchronization to prevent request rejection."},"jwt":{"type":"object","description":"A JSON Web Token (JWT) used for securely transmitting information between parties as a JSON object. This token is typically used for authentication and authorization purposes, ensuring that the client has valid credentials to access protected resources. The JWT contains encoded header, payload, and signature sections that verify the token's integrity and authenticity.\n**Field behavior**\n- Must be a valid JWT string following the standard format: header.payload.signature.\n- Used to authenticate API requests and authorize access to specific endpoints.\n- Typically included in the Authorization header as a Bearer token.\n- Should have an expiration time to enhance security.\n**Implementation guidance**\n- Validate the JWT on the server side to ensure it is properly signed and not expired.\n- Use secure algorithms (e.g., RS256 or HS256) for signing the token.\n- Store sensitive information in the payload with caution, as JWTs can be decoded by clients.\n- Refresh tokens should be used to obtain new JWTs when the current one expires.\n**Examples**\n- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\n- eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJleGFtcGxlLmNvbSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJleHAiOjE2MjQ2MjQwMDB9.DQABCD1234abcd5678efgh9012ijkl3456mnop7890qrstuv\n**Important notes**\n- JWTs should be transmitted over secure channels (HTTPS) to prevent interception.\n- Do not store JWTs in insecure storage locations on the client side (e.g., localStorage) to avoid XSS attacks.\n- Always verify the token's signature and claims before granting access.\n- Be aware of token expiration and implement proper handling for expired tokens.\n**Dependency chain**\n- Depends on the authentication mechanism generating the JWT.\n- Requires a"}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/iClients/{_id}":{"get":{"summary":"Get an iClient","description":"Retrieves a specific iClient by its unique identifier.\n","operationId":"getIClientById","tags":["iClients"],"parameters":[{"in":"path","name":"_id","required":true,"schema":{"type":"string"},"description":"The unique identifier of the iClient"}],"responses":{"200":{"description":"iClient retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## Update an iClient > Replaces an existing iClient configuration. All mutable fields must be\ > provided; omitted fields are reset to defaults.
```json {"openapi":"3.1.0","info":{"title":"iClients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Configuration for iclient","required":["provider"],"properties":{"_httpConnectorId":{"type":"string","format":"objectId","description":"Specifies the unique identifier for the HTTP connector used to establish network communication. This ID links the configuration to a specific HTTP connector instance, enabling the system to route requests appropriately.\n\n**Field behavior**\n- Accepts a string representing the connector's unique ID.\n- Used to reference an existing HTTP connector configuration.\n- Required when the operation depends on a specific HTTP connector.\n- Immutable once set during the lifecycle of the configuration.\n\n**Implementation guidance**\n- Ensure the ID corresponds to a valid and active HTTP connector within the system.\n- Validate the format of the ID to match expected patterns (e.g., UUID or predefined naming conventions).\n- Use this field to dynamically select or switch HTTP connectors in multi-connector environments.\n- Handle cases where the specified connector ID does not exist or is unavailable.\n\n**Examples**\n- \"connector-1234abcd\"\n- \"http-conn-5678efgh\"\n- \"uuid-550e8400-e29b-41d4-a716-446655440000\"\n\n**Important notes**\n- This field is critical for routing HTTP requests correctly.\n- Incorrect or missing connector IDs may lead to failed connections or errors.\n- The connector ID must be managed securely to prevent unauthorized access.\n\n**Dependency chain**\n- Depends on the existence of HTTP connector configurations within the system.\n- May influence or be influenced by authentication, proxy, or network settings tied to the connector.\n\n**Technical details**\n- Typically stored as a string data type.\n- May be used as a key in lookup tables or configuration maps.\n- Should be indexed for efficient retrieval in large-scale systems."},"_httpConnectorApiId":{"type":"string","format":"objectId","description":"Specifies the unique identifier of the HTTP Connector API associated with the current configuration or operation. This ID is used to reference and link the HTTP Connector API within the system, enabling seamless integration and communication between components.\n\n**Field behavior**\n- Acts as a reference pointer to a specific HTTP Connector API instance.\n- Must be a valid and existing API identifier within the system.\n- Used to establish connections and route requests appropriately.\n- Typically immutable once set to ensure consistent API linkage.\n\n**Implementation guidance**\n- Validate the ID against the list of available HTTP Connector APIs before assignment.\n- Ensure the ID format complies with the system’s identifier standards (e.g., UUID or specific naming conventions).\n- Handle cases where the referenced API ID does not exist or is deprecated.\n- Use this property to dynamically bind or switch HTTP Connector APIs in configurations.\n\n**Examples**\n- \"api-123e4567-e89b-12d3-a456-426614174000\"\n- \"http-connector-v2\"\n- \"connectorApi_987654321\"\n\n**Important notes**\n- This property is critical for routing HTTP requests correctly.\n- Incorrect or missing IDs can lead to failed API calls or misrouted traffic.\n- Changes to this ID should be managed carefully to avoid breaking integrations.\n- May require appropriate permissions to read or modify.\n\n**Dependency chain**\n- Depends on the existence of the HTTP Connector API registry or catalog.\n- Used by components responsible for HTTP request handling and routing.\n- May influence authentication, authorization, and logging mechanisms tied to the API.\n\n**Technical details**\n- Typically stored as a string data type.\n- Should be indexed for efficient lookup in large systems.\n- May be linked to metadata describing the HTTP Connector API’s capabilities and endpoints.\n- Often integrated with API management tools or service registries."},"enableIClientReferences":{"type":"boolean","description":"Determines whether the system should enable support for iClient references, allowing integration and interaction with iClient components or services. This setting controls the activation of features that facilitate communication, data exchange, or functionality extension through iClient references.\n\n**Field behavior**\n- When set to true, iClient references are enabled, allowing the system to recognize and process iClient-related interactions.\n- When set to false, iClient references are disabled, and any related functionality will be ignored or unavailable.\n- The field typically accepts a boolean value.\n\n**Implementation guidance**\n- Enable this setting only if your application requires integration with iClient components.\n- Ensure that enabling this does not conflict with other system configurations or security policies.\n- Validate the impact on performance and compatibility when toggling this setting.\n\n**Examples**\n- true: Enables iClient references, allowing the system to interact with iClient services.\n- false: Disables iClient references, preventing any iClient-related processing.\n\n**Important notes**\n- Enabling iClient references may require additional permissions or configurations on the client or server side.\n- Disabling this feature can improve security by limiting external references but may reduce functionality.\n- Changes to this setting might require a system restart or reinitialization to take effect.\n\n**Dependency chain**\n- May depend on the presence of iClient libraries or modules within the system.\n- Could be linked to authentication or authorization settings related to client references.\n- Might interact with other integration or communication-related configuration properties.\n\n**Technical details**\n- Typically implemented as a boolean flag in the configuration.\n- Controls conditional logic paths that handle iClient reference processing.\n- May influence API endpoints, middleware behavior, or client-server communication protocols."},"formType":{"type":"string","enum":["assistant","http"],"description":"Specifies which UI form is used to configure this iClient in integrator.io.\n\n**Critical:** How this is determined in the UI\n- If `_httpConnectorId` is set, the UI uses the **assistant** form.\n- If `_httpConnectorId` is not set, the UI uses the **http** form.\n\nThe **assistant** form is used for applications where integrator.io provides a guided setup assistant to make configuration easier.\n\n**Field behavior**\n- Controls the form layout and fields displayed in the UI.\n- May affect validation and conditional rendering in the UI.\n- Must be one of: `assistant`, `http`.\n\n**Implementation guidance**\n- Prefer letting the UI default this value based on `_httpConnectorId` unless you have a specific reason to override it.\n- Use `assistant` when configuring via an iClient assistant-backed application.\n- Use `http` for the standard HTTP configuration form.\n\n**Examples**\n- `assistant`\n- `http`\n\n**Important notes**\n- The value must be lowercase (`assistant` or `http`).\n- Changing this value impacts the UI experience for configuring the iClient.\n\n**Dependency chain**\n- Depends on whether the iClient is tied to an HTTP Connector (`_httpConnectorId`).\n- Influences which UI renderer is selected for the resource.\n\n**Technical details**\n- Stored as a lowercase string enum."},"settings":{"type":"object","description":"An object containing configuration options that customize the behavior and features of the system or application. This property allows users or developers to specify various parameters, preferences, and toggles that influence how the system operates, enabling flexible and dynamic adjustments to meet different requirements.\n\n**Field behavior**\n- Accepts a structured set of key-value pairs representing different configuration settings.\n- Can include nested objects to group related settings logically.\n- Modifications to this property typically affect system behavior immediately or upon the next initialization.\n- Supports enabling or disabling features, setting thresholds, defining modes, and other customizable options.\n\n**Implementation guidance**\n- Validate the structure and data types of the settings to ensure correctness.\n- Provide default values for unspecified settings to maintain predictable behavior.\n- Allow extensibility to accommodate future settings without breaking compatibility.\n- Document each configurable option clearly to guide users in setting appropriate values.\n\n**Examples**\n- Setting a timeout duration with `\"timeout\": 3000`.\n- Configuring logging levels with `\"logging\": {\"level\": \"verbose\", \"output\": \"file\"}`.\n- Toggling feature flags such as `\"features\": {\"betaAccess\": true, \"newUI\": false}`.\n\n**Important notes**\n- Changes to settings may require system restart or reinitialization to take effect.\n- Improper configuration can lead to unexpected behavior or degraded performance.\n- Sensitive settings should be protected and validated to prevent security risks.\n- The settings object should be kept as concise as possible to avoid complexity.\n\n**Dependency chain**\n- Dependent on the system's configuration management module.\n- May influence or be influenced by user preferences and environment variables.\n- Interacts with feature toggles, access controls, and runtime parameters.\n\n**Technical details**\n- Typically represented as a JSON object or equivalent data structure.\n- Supports various data types including strings, numbers, booleans, arrays, and nested objects.\n- May be stored in configuration files, databases, or managed via APIs.\n- Should support serialization and deserialization for persistence and transmission."},"settingsForm":{"type":"object","description":"An object representing the configuration and structure of a settings form used to capture user preferences or application parameters. This form typically includes fields, validation rules, default values, and UI metadata necessary for rendering and processing the settings interface.\n\n**Field behavior**\n- Defines the layout and components of the settings form.\n- Contains input fields with associated validation and default values.\n- Supports dynamic updates based on user interaction or external data.\n- Facilitates submission and retrieval of user-configured settings.\n\n**Implementation guidance**\n- Structure the form object to include field definitions, types, labels, and validation constraints.\n- Include metadata for UI rendering such as placeholders, tooltips, and grouping.\n- Ensure validation rules are comprehensive to prevent invalid input.\n- Support extensibility to add or modify fields without breaking existing functionality.\n\n**Examples**\n- A form object with fields for username, email preferences, and notification settings.\n- A nested form structure with sections for privacy, display, and account management.\n- Validation rules specifying required fields and acceptable value ranges.\n\n**Important notes**\n- The form should be designed to accommodate localization and accessibility standards.\n- Changes to the form structure may require corresponding updates in the UI and backend processing.\n- Ensure sensitive data fields are handled securely and comply with privacy regulations.\n\n**Dependency chain**\n- Depends on UI components to render the form fields.\n- Relies on validation logic to enforce input correctness.\n- Interacts with backend services to save and retrieve settings data.\n\n**Technical details**\n- Typically represented as a JSON object or similar structured data format.\n- May include nested objects or arrays to represent complex form hierarchies.\n- Validation rules can be expressed using standard schemas or custom logic.\n- Supports integration with form libraries or frameworks for rendering and state management."},"provider":{"type":"string","enum":["google","salesforce","azureoauth","windowslive","shopify","integrator","zendesk","bigcommerce","netsuite","ebay","ebay-xml","asana","box","dropbox","clover","servicenow","jobvite","twilio","certify","dropbox","squareup","docusign","woocommerce","microsoftbusinesscentral","custom_oauth2","amazonmws"],"description":"Specifies the **authentication provider/method** used by this iClient.\n\nThis value determines which authentication flow and credential fields are used (e.g., Google OAuth, Salesforce OAuth, NetSuite token-based auth, or a custom OAuth2 provider).\n\n**Field behavior**\n- Required.\n- Must be one of the supported provider enum values.\n- Drives the UI and validation rules for which authentication settings are shown/required.\n\n**Implementation guidance**\n- Pick the provider that matches the system you are authenticating against.\n- For generic OAuth2 providers, use `custom_oauth2`.\n- Ensure the corresponding auth configuration under `oauth2`, `jwt`, or provider-specific sections is populated as needed.\n\n**Examples**\n- google\n- salesforce\n- netsuite\n- custom_oauth2\n\n**Important notes**\n- This is not a human/vendor label — it is the provider key that selects an authentication method.\n\n**Dependency chain**\n- Influences which auth sub-configurations are applicable (for example, `oauth2.*`, `netsuite.*`, `salesforce.*`, `jwt.*`).\n\n**Technical details**\n- Stored as a lowercase string enum (see the `enum` list for allowed values)."},"name":{"type":"string"},"published":{"type":"boolean","description":"Indicates whether this iClient is published (available/visible for use).\n\n**Field behavior**\n- Boolean flag: `true` or `false`.\n- Used to control publication status in the UI.\n\n**Implementation guidance**\n- Default to `false` unless you intend to publish the iClient.\n\n**Examples**\n- `true`\n- `false`"},"enableJWT":{"type":"boolean","description":"Enables use of an additional **JWT assertion** as part of an OAuth authentication flow.\n\nUse this field when the OAuth provider requires a JWT assertion as a component of the OAuth specification. When enabled, you can use the Handlebars path `{{{iClient.jwt.token}}}` to obtain the JWT token value, which is then used in the **request body of the token URL** to generate an access token.\n\n**Field behavior**\n- When `true`, the iClient includes a JWT assertion/token as part of the OAuth token request.\n- When `false`, the OAuth flow does not incorporate a JWT assertion component.\n\n**Implementation guidance**\n- Enable only when your OAuth provider requires JWT assertion.\n- Populate the `jwt` configuration (e.g., `iClient.jwt.*`) so `{{{iClient.jwt.token}}}` can be resolved.\n- Use the resolved JWT token in the token request body parameters for the OAuth token URL, as required by the provider.\n\n**Examples**\n- `true` (OAuth token request includes a JWT assertion component)\n- `false` (standard OAuth flow without JWT assertion)\n\n**Important notes**\n- This flag is for **OAuth JWT assertion** use-cases; it does not mean “all requests must include a JWT Authorization header.”\n- If enabled without configuring `iClient.jwt`, token generation will fail.\n\n**Dependency chain**\n- Depends on `iClient.jwt` fields and the provider’s OAuth token request requirements.\n- Used when constructing the token URL request body for OAuth.\n\n**Technical details**\n- The JWT token can be referenced via `{{{iClient.jwt.token}}}` during request templating."},"netsuite":{"type":"object","properties":{"consumerKey":{"type":"string","description":"The NetSuite consumer key value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `consumerKey_crypt`/`consumerKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext consumer key here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"consumerSecret":{"type":"string","description":"The NetSuite consumer secret value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `consumerSecret_crypt`/`consumerSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext consumer secret here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."}},"description":"Configuration settings and credentials required to integrate with the NetSuite platform, enabling seamless data synchronization and interaction with NetSuite's ERP and CRM services. This property typically includes authentication details, API endpoints, and any necessary parameters for establishing a secure connection.\n\n**Field behavior**\n- Holds all necessary information to authenticate and communicate with NetSuite APIs.\n- Used to configure integration settings such as account ID, role, and environment.\n- Enables data exchange between the application and NetSuite for operations like record creation, updates, and queries.\n- May support multiple authentication methods, including token-based and OAuth.\n\n**Implementation guidance**\n- Ensure sensitive credentials are stored securely and encrypted.\n- Validate all required fields before attempting connection to NetSuite.\n- Support environment-specific configurations for different environments.\n- Handle error responses gracefully to maintain integration stability.\n- Keep the configuration up to date with NetSuite API version changes.\n\n**Examples**\n- API credentials including consumer key, consumer secret, token ID, and token secret.\n- Account ID and role ID for specifying the NetSuite account and user role.\n- URLs for NetSuite REST or SOAP API endpoints.\n- Flags or settings indicating the target environment.\n\n**Important notes**\n- Incorrect or outdated credentials will prevent successful integration.\n- NetSuite API limits and governance should be considered to avoid throttling.\n- Regularly review and rotate credentials to maintain security.\n- Integration may require specific permissions within NetSuite roles.\n\n**Dependency chain**\n- Dependent on secure storage mechanisms for credentials.\n- Relies on network connectivity to NetSuite services.\n- May depend on other configuration properties like logging or retry policies.\n\n**Technical details**\n- Typically includes OAuth 1.0a or token-based authentication parameters.\n- May require JSON or XML formatted configuration data.\n- Supports both REST and SOAP API protocols depending on use case.\n- Configuration format should align with NetSuite’s API specification requirements."},"oauth2":{"type":"object","properties":{"clientId":{"type":"string","description":"The unique identifier assigned to a client application during the OAuth 2.0 registration process. This client ID is used to identify the application when making authorization requests to the OAuth 2.0 authorization server. It is a public value that is included in authorization requests and token exchanges to associate the requests with the registered client.\n\n**Field behavior**\n- Must be a unique string assigned by the authorization server.\n- Used in authorization and token request flows to identify the client application.\n- Typically remains constant for the lifetime of the client registration.\n- Should be included in all OAuth 2.0 requests where client identification is required.\n\n**Implementation guidance**\n- Obtain the client ID from the OAuth 2.0 provider during client registration.\n- Store the client ID securely within the application configuration.\n- Do not treat the client ID as a secret; it can be exposed in URLs and logs.\n- Validate the client ID format according to the OAuth provider’s specifications.\n\n**Examples**\n- \"abc123xyz\"\n- \"myapp-client-001\"\n- \"1234567890abcdef\"\n\n**Important notes**\n- The client ID is distinct from the client secret; the latter must be kept confidential.\n- Exposure of the client ID does not compromise security but is necessary for proper OAuth flows.\n- Ensure the client ID matches exactly the value registered with the OAuth provider to avoid authentication errors.\n\n**Dependency chain**\n- Dependent on successful client registration with the OAuth 2.0 authorization server.\n- Used in conjunction with client secret (if applicable) during token requests.\n- Required for constructing authorization URLs and token exchange requests.\n\n**Technical details**\n- Typically a string of alphanumeric characters, sometimes including dashes or underscores.\n- May be case-sensitive depending on the OAuth provider.\n- Passed as a query parameter or in the request body during OAuth flows.\n- Must conform to the OAuth 2.0 specification and provider-specific requirements."},"clientSecret":{"type":"string","description":"The OAuth 2.0 **client secret** value.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this secret encrypted at rest (for example as `clientSecret_crypt` and `clientSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a secret is already set.\n\n**Implementation guidance**\n- Provide the plain client secret value here to set/update it.\n- To keep the existing secret unchanged during an update, omit this field (or, if the API/UI returns a masked value, keep `\"******\"` as-is)."},"scope":{"type":"array","items":{"type":"string"},"description":"OAuth 2.0 scopes requested for the access token.\n\n**API behavior:** the API accepts a string on input but always\nreturns an **array of strings** in responses. When you send a\nspace-delimited string like `\"openid profile\"`, the response\nwraps it as `[\"openid profile\"]`.\n\n**Examples**\n- `[]`\n- `[\"openid profile email\"]`\n- `[\"read\", \"write\"]`"},"scopeDelimiter":{"type":"string","description":"Specifies the character or string used to separate multiple OAuth2 scopes within a single authorization request or token. This delimiter enables the parsing and interpretation of scope values when they are provided as a concatenated string. Common delimiters include spaces, commas, or other characters depending on the OAuth2 provider's implementation.\n\n**Field behavior**\n- Defines how multiple scopes are split and recognized in authorization requests.\n- Ensures correct parsing of scope strings when multiple scopes are requested simultaneously.\n- Influences the format of the scope parameter in OAuth2 authorization URLs and tokens.\n\n**Implementation guidance**\n- Choose a delimiter that aligns with the OAuth2 provider's specification or defaults (e.g., space is standard per OAuth2 spec).\n- Ensure consistent use of the delimiter across all OAuth2 requests and responses.\n- Validate scope strings to correctly split and handle multiple scopes using this delimiter.\n- Document the chosen delimiter clearly for developers integrating with the API.\n\n**Examples**\n- Space character (\" \") as a delimiter: \"read write delete\"\n- Comma (\",\") as a delimiter: \"read,write,delete\"\n- Semicolon (\";\") as a delimiter: \"read;write;delete\"\n\n**Important notes**\n- The OAuth2 specification (RFC 6749) recommends using a space character as the scope delimiter.\n- Some OAuth2 providers may use non-standard delimiters; this property allows customization to accommodate those cases.\n- Incorrect delimiter configuration can lead to authorization failures or incorrect scope parsing.\n- When omitted, the default delimiter is typically a space character.\n\n**Dependency chain**\n- Depends on the OAuth2 authorization server's scope formatting requirements.\n- Influences how the 'scope' parameter in authorization requests and tokens is constructed and parsed.\n- May affect downstream components that interpret or validate scopes.\n\n**Technical details**\n- Typically a single character but can be a string if supported.\n- Used in string splitting functions to parse scope lists.\n- Should be URL-encoded if it is a special character in URLs.\n- Must be consistent with the OAuth2 provider's expectations to ensure interoperability."},"redirectUri":{"type":"string","description":"The URI to which the authorization server will redirect the user-agent after granting or denying access. This URI must be registered with the authorization server and should exactly match one of the pre-registered redirect URIs to prevent security vulnerabilities such as open redirect attacks. It is used in OAuth 2.0 authorization flows to receive authorization codes or access tokens securely.\n\n**Field behavior**\n- Specifies the callback endpoint for the authorization response.\n- Must be an absolute URI.\n- Used to return authorization codes or tokens after user consent.\n- Validated against pre-registered URIs to ensure security.\n\n**Implementation guidance**\n- Ensure the redirect URI is registered with the authorization server before use.\n- Use HTTPS to protect the integrity and confidentiality of the redirect.\n- Avoid using wildcard or overly broad redirect URIs.\n- Validate the redirect URI strictly on the server side to prevent open redirect vulnerabilities.\n\n**Examples**\n- https://client.example.com/callback\n- https://app.example.com/oauth2/callback\n- https://localhost:8080/auth/callback (for development purposes)\n\n**Important notes**\n- Mismatched redirect URIs will cause authorization requests to fail.\n- Redirect URIs should not contain fragments (#).\n- Avoid using query parameters unless necessary and registered.\n- The redirect URI is critical for security; improper configuration can lead to token leakage.\n\n**Dependency chain**\n- Depends on the authorization server's registered redirect URIs.\n- Used in conjunction with client_id and response_type parameters.\n- Integral to OAuth 2.0 authorization code and implicit grant flows.\n\n**Technical details**\n- Must conform to URI syntax as per RFC 3986.\n- Typically uses HTTPS scheme for security.\n- Should be URL-encoded when included in authorization requests.\n- The authorization server compares the redirect URI in the request with the registered URIs for exact match or pattern match depending on server policy."},"clientCredentialsLocation":{"type":"string","enum":["basicauthheader","body"],"description":"Specifies the location within the HTTP request where the client credentials (such as client ID and client secret) should be included when using the OAuth 2.0 client credentials grant type. This setting determines whether the credentials are sent in the request header (typically using the Authorization header with Basic authentication) or in the request body as form parameters.\n\n**Field behavior**\n- Defines where to place client credentials during the token request.\n- Accepts values indicating header or body placement.\n- Influences how the authentication server receives and validates client credentials.\n\n**Implementation guidance**\n- Use \"header\" to send credentials via the Authorization header using Basic authentication.\n- Use \"body\" to include credentials as form parameters in the POST request body.\n- Ensure compatibility with the OAuth 2.0 server’s expected credential location.\n- Validate that the chosen location aligns with security best practices and server requirements.\n\n**Examples**\n- \"header\" — client credentials sent in the Authorization header.\n- \"body\" — client credentials sent as form parameters in the request body.\n\n**Important notes**\n- Sending credentials in the header is generally preferred for security reasons.\n- Some OAuth 2.0 servers may only support one method; verify server documentation.\n- Incorrect configuration may lead to authentication failures.\n- Avoid exposing client credentials in URLs or query parameters.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 client credentials grant type being used.\n- Works in conjunction with clientId and clientSecret properties.\n- Affects the construction of the token request sent to the authorization server.\n\n**Technical details**\n- When set to \"header\", credentials are base64-encoded and included in the Authorization header.\n- When set to \"body\", credentials are included as \"client_id\" and \"client_secret\" form parameters.\n- Must comply with the OAuth 2.0 specification (RFC 6749) regarding client authentication methods."},"validDomainNames":{"type":"array","items":{"type":"string"},"description":"A list of domain names used to validate the OAuth URLs (Authorization, Access Token, Revoke Token).\n\nProvide each unique domain once (no scheme, no path).\n\n**Examples**\n- `[\"domain.com\"]`\n- `[\"domain.com\", \"domain1.com\", \"domain2.com\"]`\n\n**Technical details**\n- Stored as an array of strings."},"grantType":{"type":"string","enum":["authorizecode","password","clientcredentials"],"description":"Specifies the OAuth 2.0 grant type used to obtain an access token from the authorization server. This parameter determines the flow of the authentication process and how the client interacts with the authorization server to request and receive tokens. Common grant types include \"authorization_code\", \"client_credentials\", \"password\", and \"refresh_token\", each serving different use cases and security considerations.\n\n**Field behavior**\n- Defines the method by which the client application requests an access token.\n- Influences the parameters required in the token request.\n- Determines the security and user interaction model of the OAuth flow.\n- Must align with the authorization server's supported grant types.\n\n**Implementation guidance**\n- Choose the grant type based on the client application's capabilities and security requirements.\n- Ensure the authorization server supports the specified grant type.\n- Validate the grant type value against the OAuth 2.0 specification and any extensions used.\n- Handle errors gracefully if an unsupported or invalid grant type is provided.\n\n**Examples**\n- \"authorization_code\" for standard web server flows involving user authorization.\n- \"client_credentials\" for machine-to-machine authentication without user involvement.\n- \"password\" for legacy applications where the user provides credentials directly.\n- \"refresh_token\" to obtain a new access token using a previously issued refresh token.\n\n**Important notes**\n- Some grant types require additional parameters (e.g., \"authorization_code\" requires a code).\n- Using the \"password\" grant type is discouraged due to security risks.\n- The choice of grant type affects the overall security posture of the application.\n- Always use secure communication channels (HTTPS) when transmitting tokens and credentials.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 authorization server configuration.\n- Influences the required request parameters and token endpoint behavior.\n- Affects client registration details and scopes granted.\n\n**Technical details**\n- Must be a string matching one of the OAuth 2.0 defined grant types or extensions.\n- Sent as a parameter in the token request payload or URL-encoded form.\n- Case-sensitive and must conform to the OAuth 2.0 specification (RFC 6749).\n- May require additional headers or parameters depending on the grant type."},"failPath":{"type":"string","description":"Path to the **auth error field** in the HTTP response body.\n\nThis field only needs to be set if the API returns a field in the HTTP response body to indicate auth errors.\nFor example, if an API returns the field `errorMessage` with the value `Auth failed`, then set this field to `errorMessage`.\n\n**Examples**\n- `errorMessage`\n- `error`\n- `errors.0.message`"},"failValues":{"type":"array","items":{"type":"string"},"description":"Values to match against the HTTP response body field identified by\n`failPath`. If any value matches, the response is treated as an\nauth failure.\n\n**Examples**\n- `[\"access_denied\", \"invalid_grant\"]`\n- `[\"error\"]`"},"failStatusCode":{"type":"number","description":"HTTP status code that indicates an OAuth2 authentication error.\n\nThis field only needs to be set if the system you are authenticating against uses a status code **other than 401** for auth errors.\nFor example, an API may return a generic `400` status code, and then use a field in the HTTP response body to indicate authentication errors.\n\n**Field behavior**\n- Determines the HTTP response status code sent upon OAuth2 failure.\n- Influences client-side error handling and user feedback.\n- Overrides default failure status codes if explicitly set.\n\n**Implementation guidance**\n- Leave unset if auth errors are returned as `401` (default behavior).\n- Set this if auth failures are returned using another status code (e.g., `400`).\n\n**Examples**\n- 401\n- 400\n\n**Important notes**\n- Setting an inappropriate status code may lead to client confusion or security risks.\n- Some clients or intermediaries may behave differently depending on the status code.\n- The status code should be accompanied by a descriptive error message in the response body.\n\n**Dependency chain**\n- Depends on OAuth2 authentication and authorization failure events.\n- Works in conjunction with error response payloads and headers.\n- May interact with logging and monitoring systems for failure tracking.\n\n**Technical details**\n- Must be an integer within the range of valid HTTP status codes (100–599).\n- Typically used in HTTP response status line.\n- Should be consistent with OAuth2 error response standards defined in RFC 6749."},"useNewAuthFailSchema":{"type":"boolean","readOnly":true,"description":"Server-managed flag indicating whether the newer auth-failure\ndetection schema is in effect. Always `true` in current API\nresponses. Do not set this field in requests."},"failures":{"type":"array","readOnly":true,"description":"Server-computed summary of the auth-failure detection rules\nderived from `failPath`, `failValues`, and `failStatusCode`.\nPresent in responses only when those fields are configured.","items":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code that triggers auth-failure detection."},"path":{"type":"string","description":"Response body path checked for failure values."},"values":{"type":"array","items":{"type":"string"},"description":"Values at `path` that indicate an auth failure."}}}},"accessTokenLocation":{"type":"string","enum":["url","header","body"],"description":"Specifies the location where the OAuth 2.0 access token should be included when making API requests. This determines how the access token is transmitted to the server, such as in the HTTP header, query parameters, or request body. Proper configuration of this field ensures that the token is sent in a manner compatible with the API's authentication requirements.\n**Field behavior**\n- Defines the method of including the access token in API requests.\n- Common values include \"header\", \"query\", or \"body\".\n- Influences how the client constructs the request for authentication.\n**Implementation guidance**\n- Verify the API specification to determine the supported token locations.\n- Use \"header\" to include the token in the Authorization header (e.g., Bearer token).\n- Use \"query\" to append the token as a URL query parameter.\n- Use \"body\" to include the token within the request payload, typically for POST requests.\n- Ensure secure transmission, especially when using query parameters.\n**Examples**\n- \"header\" — Access token sent in the Authorization header.\n- \"query\" — Access token appended as ?access_token=XYZ in the URL.\n- \"body\" — Access token included in the POST request body parameters.\n**Important notes**\n- Sending tokens in query parameters can expose them in logs or browser history; use with caution.\n- The chosen location must align with the OAuth 2.0 server's expectations.\n- Some APIs may only support one method; incorrect configuration can lead to authentication failures.\n**Dependency chain**\n- Depends on the OAuth 2.0 flow and server requirements.\n- Works in conjunction with the access token value and token type.\n- Influences request construction and security considerations.\n**Technical details**\n- When set to \"header\", typically uses the \"Authorization: Bearer \" format.\n- When set to \"query\", appends the token as a URL parameter, often named \"access_token\".\n- When set to \"body\", includes the token in the request payload, usually as a form parameter.\n- Must be handled securely to prevent token leakage."},"accessTokenHeaderName":{"type":["string","null"],"description":"Header name used to send the OAuth 2.0 access token.\n\n**Examples**\n- `Authorization` (typically with value `Bearer `)\n- `X-Access-Token`"},"accessTokenPath":{"type":"string","description":"Specifies the relative URL path on the OAuth2 authorization server where the access token request should be sent. This path is appended to the base URL of the authorization server to form the full endpoint for obtaining an access token during the OAuth2 authentication flow. It is essential for enabling clients to exchange authorization grants for access tokens securely.\n\n**Field behavior**\n- Defines the endpoint path for access token requests in the OAuth2 flow.\n- Must be a valid relative URL path starting with a forward slash (/).\n- Used during the token exchange phase after obtaining an authorization code or other grant types.\n- Typically combined with the authorization server's base URL to form the complete token endpoint URL.\n\n**Implementation guidance**\n- Ensure the path corresponds exactly to the OAuth2 server's token endpoint specification.\n- Validate that the path is correctly formatted and accessible.\n- Avoid including query parameters or fragments in this path; it should be a clean URL path.\n- Confirm compatibility with the OAuth2 server's expected token endpoint URL structure.\n\n**Examples**\n- /oauth2/token\n- /api/v1/access_token\n- /auth/token\n\n**Important notes**\n- This path is critical for the OAuth2 token exchange process; incorrect configuration will prevent successful authentication.\n- It should not include the full URL, only the path component.\n- Must align with the OAuth2 server's documentation to ensure interoperability.\n- Often used in conjunction with other OAuth2 properties like client ID, client secret, and authorization path.\n\n**Dependency chain**\n- Depends on the base URL of the OAuth2 authorization server.\n- Used alongside authorizationPath and other OAuth2 configuration properties.\n- Integral to the OAuth2 token grant process.\n\n**Technical details**\n- Expected to be a URI path string.\n- Should begin with a forward slash (/).\n- Combined with the OAuth2 server's base URL to form the full token endpoint URI.\n- Utilized in HTTP POST requests to obtain access tokens."},"refreshTokenPath":{"type":"string","description":"The relative or absolute URL path used to request a refresh token from the OAuth 2.0 authorization server. This endpoint is typically called when the current access token has expired or is about to expire, allowing the client to obtain a new access token without requiring the user to re-authenticate. The path should conform to the OAuth 2.0 specification for token refresh requests and support the necessary HTTP methods, usually POST.\n\n**Field behavior**\n- Specifies the endpoint for refreshing OAuth 2.0 access tokens.\n- Used by the client application to maintain authenticated sessions seamlessly.\n- Invoked automatically by the client when the access token expires or is near expiration.\n- Must be accessible and correctly configured on the authorization server.\n\n**Implementation guidance**\n- Ensure the path is correctly formatted as a relative or absolute URL.\n- Confirm that the authorization server supports refresh token requests at this endpoint.\n- Secure the endpoint with appropriate authentication and authorization measures.\n- Validate that the client credentials and refresh token are correctly handled during the request.\n- Handle error responses gracefully, such as invalid or expired refresh tokens.\n\n**Examples**\n- \"/oauth2/token/refresh\"\n- \"https://auth.example.com/oauth2/token\"\n- \"/api/v1/auth/refresh-token\"\n\n**Important notes**\n- This path is distinct from the initial token request endpoint.\n- The refresh token flow requires that the client has previously obtained a refresh token.\n- Not all OAuth 2.0 providers support refresh tokens; verify compatibility.\n- The endpoint must support secure communication protocols (e.g., HTTPS).\n\n**Dependency chain**\n- Depends on the existence of a valid refresh token issued during initial authentication.\n- Works in conjunction with the access token and client credentials.\n- Related to the OAuth 2.0 token endpoint configuration.\n\n**Technical details**\n- Typically uses the HTTP POST method with form-encoded parameters.\n- Requires parameters such as grant_type=refresh_token and the refresh_token itself.\n- Responses include a new access token and optionally a new refresh token.\n- Must handle scopes and token expiration as per OAuth 2.0 standards."},"scheme":{"type":"string","description":"Specifies the OAuth 2.0 authorization scheme used for securing API requests. This field defines the method by which the client obtains and presents access tokens to authenticate and authorize API calls. Common schemes include \"authorization_code\", \"implicit\", \"password\", and \"client_credentials\", each representing a different OAuth 2.0 flow tailored to various client types and security requirements.\n\n**Field behavior**\n- Determines the OAuth 2.0 flow applied for token acquisition.\n- Influences how clients interact with the authorization server.\n- Guides the expected parameters and endpoints involved in the authentication process.\n\n**Implementation guidance**\n- Choose the scheme that best fits the client application type and security context.\n- Ensure the scheme aligns with the OAuth 2.0 specification and server capabilities.\n- Clearly document the chosen scheme to aid client developers in implementation.\n\n**Examples**\n- \"authorization_code\" for server-side web applications.\n- \"implicit\" for single-page applications.\n- \"password\" for trusted applications with user credentials.\n- \"client_credentials\" for machine-to-machine authentication.\n\n**Important notes**\n- Selecting an inappropriate scheme can lead to security vulnerabilities.\n- Some schemes may require additional parameters or configurations.\n- The scheme impacts token lifecycle and refresh mechanisms.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 specification version supported.\n- Interacts with token endpoint and authorization endpoint configurations.\n- Influences client registration and credential management.\n\n**Technical details**\n- Typically represented as a string value.\n- Must conform to recognized OAuth 2.0 flow identifiers.\n- Used by client libraries to determine authentication steps."},"accessTokenParamName":{"type":"string","description":"Parameter name used when the access token is passed as a query/body parameter (instead of a header).\n\n**Examples**\n- `access_token`\n- `token`\n- `auth_token`"},"useIClientFields":{"type":"boolean","description":"Determines whether to utilize the legacy iClient-specific fields in the OAuth2 configuration instead of the standard OAuth2 fields. This option is typically used for backward compatibility with systems or integrations that rely on the older iClient field structure.\n\n**Field behavior**\n- When set to true, the system uses iClient-specific OAuth2 fields for authentication.\n- When set to false or omitted, the system defaults to standard OAuth2 fields.\n- Influences how client credentials and tokens are processed during OAuth2 flows.\n\n**Implementation guidance**\n- Enable this flag only if integrating with legacy systems requiring iClient fields.\n- Ensure that the corresponding iClient fields are properly configured when this is enabled.\n- Validate compatibility with the OAuth2 provider before enabling this option.\n\n**Examples**\n- true: Use iClient-specific fields for OAuth2 authentication.\n- false: Use standard OAuth2 fields for authentication.\n\n**Important notes**\n- Enabling this may affect interoperability with modern OAuth2 providers.\n- This setting is primarily for backward compatibility and may be deprecated in future releases.\n- Misconfiguration can lead to authentication failures.\n\n**Dependency chain**\n- Depends on the presence of iClient-specific OAuth2 fields in the configuration.\n- Affects OAuth2 token request and refresh processes.\n\n**Technical details**\n- Overrides default OAuth2 client ID, secret, and token endpoint parameters with iClient equivalents.\n- May alter request payload structure during OAuth2 token exchanges.\n- Typically used in environments where legacy iClient authentication flows are required."},"pkceCodeChallengeMethod":{"type":["string","null"],"enum":["plain","s256"],"description":"PKCE code challenge method used for the OAuth 2.0 authorization code flow (RFC 7636).\n\n**Field behavior**\n- `s256` is recommended.\n- `plain` should only be used if required by the provider.\n\n**Examples**\n- `s256`\n- `plain`"},"auth":{"type":"object","properties":{"uri":{"type":"string","description":"The URI endpoint where the OAuth 2.0 authorization server accepts authorization requests. This URI is used by clients to initiate the authorization flow, typically by redirecting the resource owner's user-agent to this address. It must be a valid HTTPS URL to ensure secure transmission of sensitive information such as authorization codes or tokens.\n\n**Field behavior**\n- Serves as the entry point for the OAuth 2.0 authorization process.\n- Used by clients to request authorization from the resource owner.\n- Typically involves redirection of the user's browser to this URI.\n- Must support standard OAuth 2.0 authorization request parameters.\n\n**Implementation guidance**\n- Ensure the URI is an HTTPS endpoint to maintain security.\n- The endpoint should conform to OAuth 2.0 specifications for authorization endpoints.\n- Validate that the URI is reachable and correctly configured to handle authorization requests.\n- Include necessary query parameters as per OAuth 2.0 standards during requests.\n\n**Examples**\n- https://authorization-server.com/oauth2/authorize\n- https://accounts.example.com/auth\n- https://login.provider.com/oauth2/auth\n\n**Important notes**\n- The URI must be registered with the OAuth 2.0 provider and match the client configuration.\n- Using HTTP instead of HTTPS is not recommended due to security risks.\n- The URI should be stable and not change frequently to avoid client misconfigurations.\n- This endpoint is distinct from the token endpoint used to exchange authorization codes for tokens.\n\n**Dependency chain**\n- Dependent on the OAuth 2.0 client configuration specifying this URI.\n- Used in conjunction with client_id, redirect_uri, response_type, and scope parameters.\n- Works alongside the token endpoint URI for completing the OAuth flow.\n\n**Technical details**\n- Must be a valid, well-formed URL.\n- Should support GET requests with query parameters for authorization requests.\n- Typically responds with redirects (HTTP 302) to the redirect_uri with authorization codes or tokens.\n- Should implement security best practices such as TLS 1.2+ and proper CORS policies."}},"description":"Specifies the authentication method and credentials required for OAuth 2.0 authorization. This property defines how the client should authenticate with the authorization server to obtain an access token. It typically includes details such as client ID, client secret, token endpoint, scopes, and grant type.\n\n**Field behavior**\n- Determines the authentication flow used in the OAuth 2.0 process.\n- Controls how credentials are presented to the authorization server.\n- Influences token acquisition and refresh mechanisms.\n- May include multiple authentication parameters depending on the grant type.\n\n**Implementation guidance**\n- Ensure all required fields for the chosen OAuth 2.0 flow are included.\n- Securely store sensitive information like client secrets.\n- Validate the format and correctness of URLs and credentials.\n- Support common grant types such as authorization code, client credentials, and password.\n- Handle token expiration and refresh logic as needed.\n\n**Examples**\n- Client credentials flow with client ID and client secret.\n- Authorization code flow with redirect URI and scopes.\n- Password grant with username and password fields.\n- Refresh token usage for renewing access tokens.\n\n**Important notes**\n- Sensitive data must be protected and not exposed in logs or error messages.\n- The authentication method must comply with OAuth 2.0 standards.\n- Misconfiguration can lead to failed authentication or security vulnerabilities.\n- Different OAuth 2.0 providers may require specific parameters or formats.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 grant type specified elsewhere in the configuration.\n- Interacts with token endpoint URLs and scope definitions.\n- May be linked to client application registration details.\n\n**Technical details**\n- Typically includes fields such as client_id, client_secret, token_url, scopes, grant_type.\n- May require encoding or encryption of credentials during transmission.\n- Supports standard OAuth 2.0 token request and response formats.\n- Should handle HTTP status codes and error responses from the authorization server."},"token":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST"],"description":"HTTP method used to call the OAuth 2.0 token endpoint.\n\n**Important notes**\n- `POST` is most common and recommended.\n- `GET` may expose sensitive data in URLs/logs."},"uri":{"type":"string","description":"The URI (Uniform Resource Identifier) specifying the endpoint where the OAuth 2.0 token request is sent to obtain an access token. This endpoint is responsible for authenticating the client and issuing tokens according to the OAuth 2.0 protocol. It must be a valid HTTPS URL to ensure secure transmission of sensitive credentials and tokens.\n\n**Field behavior**\n- Defines the exact URL to which token requests are made during the OAuth 2.0 flow.\n- Used by clients to exchange authorization grants or refresh tokens for access tokens.\n- Must support the OAuth 2.0 token request parameters and response formats.\n- Typically accessed via HTTP POST requests.\n\n**Implementation guidance**\n- Ensure the URI is a fully qualified HTTPS URL to maintain security.\n- Confirm the endpoint supports the OAuth 2.0 token exchange specification.\n- Validate the URI format before use to prevent runtime errors.\n- Document any additional headers or parameters required by the token endpoint.\n\n**Examples**\n- https://auth.example.com/oauth2/token\n- https://login.provider.com/oauth2/v1/token\n- https://api.service.com/oauth/token\n\n**Important notes**\n- The URI must be reachable and responsive to token requests.\n- Using HTTP instead of HTTPS is discouraged due to security risks.\n- The token endpoint may require client authentication via headers or request body.\n- Changes to this URI can disrupt the OAuth 2.0 authentication flow.\n\n**Dependency chain**\n- Dependent on the OAuth 2.0 authorization server configuration.\n- Used in conjunction with client credentials and grant types.\n- Related to other OAuth 2.0 endpoints such as authorization URI and revocation URI.\n\n**Technical details**\n- Must conform to URI syntax as per RFC 3986.\n- Typically accessed using HTTP POST with content type application/x-www-form-urlencoded.\n- Responses are usually JSON objects containing access tokens and metadata.\n- May support additional OAuth 2.0 extensions like PKCE or client authentication methods."},"body":{"type":"string","description":"The body property represents the payload content sent in the HTTP request when obtaining an OAuth 2.0 token. It typically includes key-value pairs such as grant type, client credentials, authorization code, refresh token, and scope, formatted according to the OAuth 2.0 specification. This property is essential for conveying the necessary parameters to the token endpoint to successfully authenticate and receive an access token.\n\n**Field behavior**\n- Contains the data sent in the HTTP request body during the token request.\n- Must include all required parameters based on the OAuth 2.0 grant type being used.\n- Often formatted as application/x-www-form-urlencoded or JSON, depending on the API requirements.\n- Is transmitted securely over HTTPS to protect sensitive information.\n\n**Implementation guidance**\n- Ensure the body includes all mandatory fields such as grant_type, client_id, client_secret, code, redirect_uri, or refresh_token as applicable.\n- Use the correct content type header matching the body format.\n- Encode parameters properly to comply with URL encoding standards if using form-urlencoded format.\n- Validate the body content before sending to avoid malformed requests.\n\n**Examples**\n- grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback&client_id=CLIENT_ID&client_secret=CLIENT_SECRET\n- { \"grant_type\": \"refresh_token\", \"refresh_token\": \"REFRESH_TOKEN\", \"client_id\": \"CLIENT_ID\" }\n\n**Important notes**\n- The exact parameters required in the body depend on the OAuth 2.0 flow implemented (authorization code, client credentials, password, refresh token).\n- Sensitive information such as client_secret should be handled securely and never exposed in logs or client-side code.\n- The body must conform to the OAuth 2.0 specification and the authorization server’s expectations.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 grant type selected.\n- Relies on correct client credentials and authorization codes obtained from prior steps.\n- Works in conjunction with HTTP headers like Content-Type and Authorization.\n\n**Technical details**\n- Typically sent as application/x-www-form-urlencoded or application/json.\n- Must be included in the POST request to the token endpoint URL.\n- Parameters are case-sensitive and must match the OAuth 2.0 specification.\n- The server response depends on the correctness and completeness of the body content."},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the token request when obtaining an OAuth 2.0 access token. These headers allow customization of the request, such as setting content types, authorization credentials, or custom metadata required by the token endpoint. The headers should be specified as key-value pairs where the key is the header name and the value is the header content.\n\n**Field behavior**\n- Overrides or supplements default headers sent in the token request.\n- Supports multiple headers to be included simultaneously.\n- Headers are sent exactly as specified without modification.\n- Used primarily during the OAuth 2.0 token exchange process.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized as per HTTP standards.\n- Avoid including sensitive information unless required and secure.\n- Validate header values to conform to expected formats (e.g., content-type).\n- Use this field to add custom headers required by specific OAuth providers.\n\n**Examples**\n- Authorization: Basic base64(client_id:client_secret)\n- Content-Type: application/x-www-form-urlencoded\n- Custom-Header: customValue\n\n**Important notes**\n- Headers specified here apply only to the token request, not to other OAuth flows.\n- Conflicts with default headers may cause token request failures.\n- Sensitive headers should be handled securely to prevent leaks.\n- Some OAuth providers may require specific headers for successful authentication.\n\n**Dependency chain**\n- Used in conjunction with oauth2.token.url and oauth2.token.body parameters.\n- May depend on client credentials or other authentication parameters.\n- Influences the HTTP request sent to the OAuth token endpoint.\n\n**Technical details**\n- Represented as a map/dictionary of string keys and string values.\n- Transmitted as HTTP headers in the token request POST or GET.\n- Supports standard HTTP header syntax and conventions.\n- Must comply with OAuth 2.0 token endpoint requirements and HTTP protocol."}},"description":"The access token issued by the OAuth 2.0 authorization server, used to authenticate and authorize API requests on behalf of the user or client. This token is typically a string representing a bearer token that must be included in the Authorization header of HTTP requests to access protected resources. It has a limited lifetime and scope, defining the permissions granted to the client.\n\n**Field behavior**\n- Represents the credential used to access protected resources.\n- Must be included in API requests to authenticate the client.\n- Has an expiration time after which it becomes invalid.\n- May be a JWT or opaque string depending on the authorization server.\n- Should be securely stored and transmitted only over HTTPS.\n\n**Implementation guidance**\n- Ensure the token is included in the Authorization header as \"Bearer {token}\".\n- Validate the token's expiration and scope before use.\n- Refresh the token using a refresh token if supported and expired.\n- Handle token revocation and errors gracefully.\n- Avoid logging or exposing the token in client-side code or URLs.\n\n**Examples**\n- \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n- \"2YotnFZFEjr1zCsicMWpAA\"\n- \"mF_9.B5f-4.1JqM\"\n\n**Important notes**\n- The token must be kept confidential to prevent unauthorized access.\n- Tokens are typically short-lived to enhance security.\n- Different APIs may require tokens with specific scopes or claims.\n- Always use secure transport (HTTPS) when transmitting tokens.\n\n**Dependency chain**\n- Obtained after successful OAuth 2.0 authorization or token exchange.\n- May depend on client credentials, authorization code, or refresh token.\n- Used in conjunction with the Authorization header in API requests.\n\n**Technical details**\n- Usually a string encoded in JWT or opaque format.\n- Contains claims or metadata about the user and permissions.\n- Includes an expiration timestamp (exp claim in JWT).\n- May include scopes defining access rights.\n- Must conform to OAuth 2.0 and OpenID Connect standards where applicable."},"refresh":{"type":"object","properties":{"body":{"type":"string","description":"The body of the HTTP request used to refresh an OAuth 2.0 access token. This typically includes parameters such as the refresh token, client credentials, grant type, and any additional required fields as specified by the OAuth 2.0 protocol. The body must be formatted according to the content type expected by the authorization server, commonly application/x-www-form-urlencoded.\n\n**Field behavior**\n- Contains all necessary parameters to request a new access token using a refresh token.\n- Must include the \"grant_type\" parameter set to \"refresh_token\".\n- Should include the \"refresh_token\" parameter with the valid refresh token value.\n- May include client authentication parameters such as \"client_id\" and \"client_secret\" if required.\n- Sent as the payload of the HTTP POST request to the token endpoint.\n\n**Implementation guidance**\n- Ensure the body is properly URL-encoded if using application/x-www-form-urlencoded content type.\n- Validate that all required parameters are present before sending the request.\n- Follow the OAuth 2.0 specification (RFC 6749) for the exact parameter names and values.\n- Handle any additional parameters required by the specific OAuth provider.\n- Securely handle sensitive information such as client secrets and refresh tokens.\n\n**Examples**\n- grant_type=refresh_token&refresh_token=xyz123&client_id=abc&client_secret=secret\n- grant_type=refresh_token&refresh_token=def456\n\n**Important notes**\n- The refresh token must be valid and not expired or revoked.\n- The authorization server may require client authentication in the body or via other means.\n- The content type header must match the format of the body (e.g., application/x-www-form-urlencoded).\n- Improper formatting or missing parameters will result in an error response from the server.\n\n**Dependency chain**\n- Depends on having a valid refresh token obtained from a previous authorization.\n- Requires knowledge of the OAuth 2.0 token endpoint URL.\n- May depend on client credentials if the server requires client authentication.\n- Relies on the correct grant_type parameter to indicate a refresh token request.\n\n**Technical details**\n- Typically sent as an HTTP POST request body.\n- Commonly uses application/x-www-form-urlencoded encoding.\n- Parameters include \"grant_type\", \"refresh_token\", and optionally \"client_id\" and \"client_secret\".\n- Must comply with OAuth 2.0 RFC 6749 Section 6 for token refresh requests."},"method":{"type":"string","enum":["GET","POST"],"description":"Specifies the HTTP method to be used when making the refresh token request in the OAuth 2.0 authentication flow. This method determines how the refresh token and related parameters are sent to the authorization server to obtain a new access token. Common HTTP methods include POST and GET, with POST being the most widely used due to its ability to securely transmit data in the request body.\n\n**Field behavior**\n- Defines the HTTP verb for the token refresh request.\n- Influences how parameters are encoded and transmitted.\n- Affects compatibility with different OAuth 2.0 server implementations.\n\n**Implementation guidance**\n- Typically set to POST for secure transmission of sensitive data.\n- Ensure the chosen method aligns with the OAuth 2.0 server’s requirements.\n- Validate that the client library or HTTP client supports the specified method.\n- Consider security implications of using GET, as parameters may be exposed in URLs.\n\n**Examples**\n- POST\n- GET\n\n**Important notes**\n- Using GET may expose refresh tokens in URLs, which can be logged or cached.\n- Some OAuth 2.0 servers may only support POST for token refresh requests.\n- The method must be consistent with the server’s expected protocol to avoid errors.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 server’s token endpoint configuration.\n- Interacts with the refresh token and client credentials parameters.\n- Influences the HTTP headers and body formatting of the request.\n\n**Technical details**\n- HTTP methods are case-insensitive but typically uppercase.\n- POST requests send parameters in the request body using application/x-www-form-urlencoded format.\n- GET requests send parameters as URL query parameters.\n- Proper handling of HTTP status codes and responses is required based on the method used."},"uri":{"type":"string","description":"Refresh token endpoint URI used to exchange a refresh token for a new access token (RFC 6749 Section 6).\n\n**Examples**\n- https://auth.example.com/oauth2/token\n- https://login.provider.com/oauth2/v1/token"},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the OAuth 2.0 refresh token request. These headers can be used to pass additional metadata, authentication information, or custom parameters required by the authorization server during the token refresh process. Typically, this may include headers such as `Content-Type`, `Authorization`, or any other custom headers mandated by the API specification.\n\n**Field behavior**\n- Accepts key-value pairs representing HTTP header names and their corresponding values.\n- Headers are included in the HTTP request sent to the token endpoint during the refresh token flow.\n- Overrides or supplements default headers set by the client or HTTP library.\n- Supports standard and custom headers as required by the OAuth 2.0 provider.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized and conform to HTTP standards.\n- Avoid including sensitive information in headers unless required and secured.\n- Validate header values to prevent injection or formatting errors.\n- Use this field to add headers like `Authorization` if the token endpoint requires client authentication via headers.\n- Do not duplicate headers that are automatically managed by the HTTP client unless overriding is necessary.\n\n**Examples**\n- `Content-Type: application/x-www-form-urlencoded`\n- `Authorization: Basic base64(client_id:client_secret)`\n- `Custom-Header: customValue`\n\n**Important notes**\n- Headers specified here apply only to the refresh token request, not to other OAuth 2.0 flows.\n- Misconfigured headers can cause token refresh failures or security issues.\n- Some OAuth 2.0 servers require specific headers for token refresh requests; consult the provider’s documentation.\n- Sensitive headers should be handled securely to prevent exposure.\n\n**Dependency chain**\n- Used in conjunction with `oauth2.refresh.tokenUrl` to make the refresh token request.\n- May depend on client authentication method specified elsewhere in the OAuth 2.0 configuration.\n- Interacts with HTTP client settings that manage default headers.\n\n**Technical details**\n- Represented as a map/dictionary of string keys and string values.\n- Translated into HTTP headers in the outgoing POST request to the token endpoint.\n- Must comply with HTTP/1.1 header field syntax and encoding rules.\n- Typically sent over HTTPS to ensure confidentiality and integrity."}},"description":"Indicates whether the OAuth2 refresh token flow is supported/enabled.\n\n**Examples**\n- `true`\n- `false`"},"revoke":{"type":"object","properties":{"uri":{"type":"string","description":"The URI endpoint where OAuth 2.0 token revocation requests are sent. This URI is used by clients to invalidate access or refresh tokens, ensuring they can no longer be used for authentication or authorization. It must be a valid HTTPS URL to guarantee secure transmission of sensitive token data.\n\n**Field behavior**\n- Accepts a single string value representing the revocation endpoint URL.\n- Used by clients to send HTTP POST requests to revoke tokens.\n- Should support standard OAuth 2.0 token revocation parameters as per RFC 7009.\n- Must be reachable and respond appropriately to revocation requests.\n\n**Implementation guidance**\n- Ensure the URI uses HTTPS to protect token data during transmission.\n- The endpoint should conform to OAuth 2.0 Token Revocation specification (RFC 7009).\n- Validate the URI format to prevent misconfiguration.\n- Document any additional headers or authentication required by the revocation endpoint.\n\n**Examples**\n- https://auth.example.com/oauth2/revoke\n- https://api.service.com/oauth2/token/revoke\n\n**Important notes**\n- The revocation URI is distinct from the authorization and token endpoints.\n- Proper implementation of token revocation enhances security by allowing clients to invalidate tokens when no longer needed.\n- Failure to provide a valid revocation URI may prevent clients from properly revoking tokens.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 authorization server configuration.\n- Related to the OAuth 2.0 token endpoint and authorization endpoint.\n- Used in conjunction with client credentials and tokens issued by the authorization server.\n\n**Technical details**\n- Typically accessed via HTTP POST with parameters such as token and token_type_hint.\n- Must handle authentication of the client making the revocation request.\n- Should return appropriate HTTP status codes indicating success or failure of revocation."},"body":{"type":"string","description":"The request body containing the parameters required to revoke an OAuth 2.0 token. This typically includes the token to be revoked and may also specify the token type hint to indicate whether the token is an access token or a refresh token. The body must be formatted according to the application/x-www-form-urlencoded MIME type as per the OAuth 2.0 Token Revocation specification (RFC 7009).\n\n**Field behavior**\n- Contains key-value pairs representing the token and optional token type hint.\n- Must be included in the HTTP POST request to the token revocation endpoint.\n- Parameters are URL-encoded in the request body.\n- Used to instruct the authorization server to invalidate a specific token.\n\n**Implementation guidance**\n- Ensure the body includes the \"token\" parameter with the token string to revoke.\n- Optionally include \"token_type_hint\" with values like \"access_token\" or \"refresh_token\" to assist the server.\n- Use application/x-www-form-urlencoded content type for the request.\n- Validate that the token parameter is present and correctly formatted before sending.\n- Handle server responses to confirm successful revocation or errors.\n\n**Examples**\n- token=SlAV32hkKG\n- token=34xkj23j4k23&token_type_hint=refresh_token\n- token=abcdef123456&token_type_hint=access_token\n\n**Important notes**\n- The token parameter is mandatory; omission will result in an error.\n- The token_type_hint is optional but recommended to improve server processing.\n- Revocation requests must be authenticated as per the authorization server’s requirements.\n- Revoking a token invalidates it immediately, preventing further use.\n- The body must not contain any additional parameters beyond those defined by the specification.\n\n**Dependency chain**\n- Depends on the OAuth 2.0 token revocation endpoint being correctly configured.\n- Requires the client to have a valid token to revoke.\n- May depend on client authentication credentials included in the request headers.\n- The server’s response depends on the correctness of the body parameters.\n\n**Technical details**\n- Content-Type: application/x-www-form-urlencoded\n- Encoding: URL-encoded key-value pairs\n- Parameters:\n - token (string, required): The token to be revoked.\n - token_type_hint (string, optional): A hint about the type of the token.\n- HTTP Method: POST\n- Conforms to RFC 7009 (OAuth 2.0 Token Revocation)"},"headers":{"type":["string","null"],"description":"A collection of HTTP headers to include in the token revocation request for OAuth 2.0. These headers can be used to specify additional metadata such as content type, authorization credentials, custom client information, or any other required HTTP headers that the revocation endpoint expects. This allows for greater flexibility and control over the HTTP request sent to the authorization server when revoking tokens.\n\n**Field behavior**\n- Accepts key-value pairs representing HTTP header names and their corresponding values.\n- Headers are included in the HTTP request sent to the token revocation endpoint.\n- Can override default headers or add custom headers as needed.\n- Supports standard headers like `Authorization`, `Content-Type`, and custom headers.\n\n**Implementation guidance**\n- Ensure header names are correctly capitalized and conform to HTTP standards.\n- Avoid including sensitive information in headers unless required and secure.\n- Validate header values to prevent injection or formatting errors.\n- Use this field to comply with specific OAuth 2.0 server requirements for token revocation.\n\n**Examples**\n- `Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0`\n- `Content-Type: application/x-www-form-urlencoded`\n- `X-Custom-Header: customValue`\n\n**Important notes**\n- Headers specified here will be sent only during the token revocation request.\n- Misconfigured headers may cause the revocation request to fail.\n- This field does not affect other OAuth 2.0 requests such as token acquisition or introspection.\n\n**Dependency chain**\n- Used in conjunction with the `oauth2.revoke.url` property specifying the revocation endpoint.\n- May depend on `oauth2.revoke.method` to determine the HTTP method used.\n- Works alongside other OAuth 2.0 configuration properties to complete the revocation flow.\n\n**Technical details**\n- Represented as a map or dictionary of string key-value pairs.\n- Incorporated into the HTTP request headers when making the revocation call.\n- Must comply with HTTP header syntax and encoding rules.\n- Typically used in HTTP POST requests to the revocation endpoint."}},"description":"Indicates whether the OAuth2 token revocation endpoint is supported/enabled (RFC 7009).\n\n**Examples**\n- `true`\n- `false`"},"username":{"type":"string","description":"The username used to authenticate the user within the OAuth2 authorization framework. This value typically represents the unique identifier assigned to the user by the authentication provider or system. It is required when performing resource owner password credentials grant or other flows that involve direct user authentication.\n\n**Field behavior**\n- Must be a non-empty string representing the user's login identifier.\n- Used in conjunction with the password to obtain an access token.\n- Should be case-sensitive depending on the authentication system.\n- Validated against the authentication provider's user database.\n\n**Implementation guidance**\n- Ensure the username is securely transmitted over HTTPS to protect user credentials.\n- Validate the format and existence of the username before processing authentication.\n- Avoid logging the username in plain text to maintain user privacy.\n- Support international characters if the authentication system allows.\n\n**Examples**\n- \"johndoe\"\n- \"user@example.com\"\n- \"alice123\"\n\n**Important notes**\n- The username must correspond to a valid user account in the OAuth2 provider.\n- Incorrect usernames will result in authentication failure.\n- Should be handled securely to prevent exposure of sensitive user information.\n\n**Dependency chain**\n- Typically used alongside the `password` property in OAuth2 password grant flows.\n- Dependent on the OAuth2 server's user management and authentication mechanisms.\n\n**Technical details**\n- Data type: string\n- Maximum length may vary depending on the OAuth2 provider.\n- Should be URL-encoded if included in query parameters or request bodies."},"password":{"type":"string","description":"The OAuth2 **password** value (used with the password grant).\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores the password encrypted at rest (for example as `password_crypt`/`password_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a password is already set.\n\n**Implementation guidance**\n- Provide the plain password value here to set/update it.\n- To keep the existing password unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"unencrypted":{"type":"object","description":"Store all **non-sensitive** fields required by your imports and exports to access the app you are connecting to.\n\nThese values can be referenced by resources within integrator.io through the iClient.\n\n**Examples**\n- `{\"email\":\"my_email@company.com\", \"accountId\": \"8675301\", \"role\":\"admin\"}`\n\n**Important notes**\n- Only store non-sensitive values here (safe to store unencrypted).\n- Use `encrypted` for secrets (passwords, tokens, keys)."},"encrypted":{"type":"object","description":"Store all **sensitive** fields required by your imports and exports to access the app you are connecting to.\n\nThese values are stored with **AES-256 encryption** and other layers of protection to keep your data safe.\nThese values can be referenced by resources within integrator.io through the iClient.\n\n**Examples**\n- `{\"password\":\"celigorocks\"}`\n- `{\"token\":\"x7if4nkovhgr63ghp\"}`\n\n**Important notes**\n- Use this for secrets (passwords, tokens, keys).\n- Values may be masked (e.g., `\"******\"`) in API responses once stored."}},"description":"Configuration settings for OAuth 2.0 authentication, enabling secure authorization and access delegation for API clients. This property typically includes details such as authorization URLs, token URLs, scopes, client credentials, and grant types supported by the OAuth 2.0 provider.\n\n**Field behavior**\n- Defines the OAuth 2.0 flow and parameters required for client authentication.\n- Specifies the endpoints for obtaining authorization and access tokens.\n- Lists the scopes that determine the level of access granted.\n- Supports multiple OAuth 2.0 grant types (e.g., authorization code, client credentials).\n- Enables secure token exchange and refresh mechanisms.\n\n**Implementation guidance**\n- Ensure URLs for authorization and token endpoints are accurate and reachable.\n- Clearly define the scopes to limit access according to least privilege principles.\n- Include client ID and client secret securely, avoiding exposure in client-side code.\n- Support refresh tokens if long-lived sessions are required.\n- Validate tokens on the server side to maintain security.\n\n**Examples**\n- Authorization code flow with authorization URL, token URL, and scopes.\n- Client credentials flow with token URL and client credentials.\n- Implicit flow configuration for single-page applications.\n- Refresh token configuration for renewing access tokens.\n\n**Important notes**\n- OAuth 2.0 configurations must comply with the security best practices to prevent token leakage.\n- Sensitive information such as client secrets should never be exposed publicly.\n- The choice of grant type depends on the client application type and security requirements.\n- Proper error handling should be implemented for token acquisition failures.\n\n**Dependency chain**\n- Depends on the presence of an OAuth 2.0 compliant authorization server.\n- Requires secure storage and transmission of client credentials.\n- Interacts with API endpoints that enforce OAuth 2.0 token validation.\n\n**Technical details**\n- Typically includes fields like authorizationUrl, tokenUrl, refreshUrl, scopes, clientId, clientSecret, and grantTypes.\n- Uses HTTPS endpoints to ensure secure communication.\n- May support PKCE (Proof Key for Code Exchange) for enhanced security in public clients.\n- Tokens are usually JWTs or opaque tokens depending on the OAuth provider implementation."},"salesforce":{"type":"object","properties":{"clientId":{"type":"string","description":"The unique identifier assigned to a client application by Salesforce during the OAuth client registration process. This ID is used to authenticate the client when making API requests and establishing a secure connection with Salesforce services. It is essential for enabling authorized access to Salesforce resources on behalf of the client application.\n**Field behavior**\n- Must be a non-empty string.\n- Used as part of the OAuth authentication flow.\n- Typically remains constant for a given client application.\n- Required for initiating API calls to Salesforce.\n**Implementation guidance**\n- Obtain this value from the Salesforce connected app configuration.\n- Store securely and avoid exposing it in client-side code.\n- Validate the format to ensure it matches Salesforce client ID patterns.\n- Use in conjunction with clientSecret for authentication.\n**Examples**\n- \"3MVG9d6T2QxX9z5l7Y8P0qR1sT2uVwXyZAbCdEfGhIjKlMnOpQrStUvWxYz123456\"\n- \"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\"\n**Important notes**\n- The clientId alone does not grant access; it must be paired with appropriate credentials and tokens.\n- Changing the clientId requires updating all integrations using it.\n- Keep the clientId confidential to prevent unauthorized access.\n**Dependency chain**\n- Dependent on the Salesforce connected app setup.\n- Works alongside clientSecret, redirectUri, and OAuth tokens.\n- Required for generating access tokens.\n**Technical details**\n- Typically a 40-character alphanumeric string.\n- Assigned by Salesforce upon connected app creation.\n- Used in HTTP headers or request parameters during OAuth flows."},"clientSecret":{"type":"string","description":"The Salesforce OAuth **client secret** value.\n\nThis is the value you provide to configure or update the Salesforce iClient. Internally, integrator.io stores this secret encrypted at rest (for example as `clientSecret_crypt` and `clientSecret_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a secret is already set.\n\n**Implementation guidance**\n- Provide the plain client secret value here to set/update it.\n- To keep the existing secret unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"apiToken":{"type":"string","description":"The API token used to authenticate requests to the Salesforce API. This token acts as a secure credential that grants access to Salesforce resources and operations, ensuring that only authorized clients can interact with the Salesforce environment. It is typically generated within Salesforce or through an OAuth flow and must be kept confidential to prevent unauthorized access.\n\n**Field behavior**\n- Used for authenticating API calls to Salesforce.\n- Must be included in the authorization header or as specified by the Salesforce API.\n- Typically has an expiration time and may require periodic renewal.\n- Invalid or expired tokens will result in authentication errors.\n\n**Implementation guidance**\n- Store the token securely, such as in environment variables or secure vaults.\n- Avoid hardcoding the token in source code or exposing it in logs.\n- Implement token refresh logic if using OAuth tokens with limited lifespans.\n- Validate the token format before use to prevent malformed requests.\n\n**Examples**\n- A long alphanumeric string like \"00Dxx0000001gPFEAY!AQ0AQJ...\"\n- OAuth access tokens obtained via Salesforce OAuth 2.0 flows.\n- Tokens generated from Salesforce connected apps for API access.\n\n**Important notes**\n- The API token is sensitive information and should be treated like a password.\n- Sharing or leaking the token can compromise Salesforce data security.\n- Ensure compliance with Salesforce security policies when handling tokens.\n- Different Salesforce environments (non-production vs production) may require different tokens.\n\n**Dependency chain**\n- Dependent on Salesforce user credentials or OAuth authorization flows.\n- Used in conjunction with the Salesforce instance URL and API endpoints.\n- May require additional headers or parameters as per Salesforce API specifications.\n\n**Technical details**\n- Typically included in HTTP headers as \"Authorization: Bearer {apiToken}\".\n- May have scopes or permissions associated depending on how it was generated.\n- Tokens may be JWTs or opaque strings depending on the authentication method.\n- Salesforce APIs validate the token on each request to authorize access."},"privateKey":{"type":"string","description":"The Salesforce private key value used for authentication flows such as JWT bearer token OAuth.\n\nThis is the value you provide to configure or update the Salesforce iClient. Internally, integrator.io stores this key encrypted at rest (for example as `privateKey_crypt`/`privateKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a key is already set.\n\n**Implementation guidance**\n- Provide the plaintext private key value here to set/update it (often PEM formatted).\n- To keep the existing private key unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"publicKey":{"type":"string","description":"The publicKey property represents the public cryptographic key used for secure data encryption, verification, or authentication processes within the Salesforce integration. This key is typically part of a public-private key pair and is used to encrypt data or verify digital signatures without exposing the private key. It ensures secure communication and data integrity between systems.\n\n**Field behavior**\n- Accepts a string value representing the public key in a standard format (e.g., PEM, DER).\n- Used to encrypt data or verify signatures in cryptographic operations.\n- Must be provided in a format compatible with the consuming system.\n- Immutable once set for a given integration instance to maintain security.\n\n**Implementation guidance**\n- Ensure the public key is generated using a secure and recognized cryptographic algorithm (e.g., RSA, ECDSA).\n- Validate the key format before accepting it to prevent errors during cryptographic operations.\n- Store the key securely and restrict access to prevent unauthorized modifications.\n- Update the key only through a controlled process to avoid breaking integrations.\n\n**Examples**\n- A PEM-encoded RSA public key string starting with \"-----BEGIN PUBLIC KEY-----\".\n- An ECDSA public key represented in base64 encoding.\n- A public key string used to verify JWT tokens issued by Salesforce.\n\n**Important notes**\n- The publicKey must correspond to the private key held securely by the entity performing signing or decryption.\n- Do not expose the private key in any API or configuration.\n- Incorrect or malformed keys will cause authentication or encryption failures.\n- Keep the key updated in case of key rotation policies.\n\n**Dependency chain**\n- Dependent on the cryptographic algorithm and key pair generation process.\n- Used by authentication, encryption, or signature verification components.\n- May be linked to other security configurations such as certificates or token validation settings.\n\n**Technical details**\n- Typically encoded in PEM or DER format.\n- May include metadata such as key type and length.\n- Should comply with relevant security standards (e.g., PKCS#1, X.509).\n- Size and algorithm choice affect security strength and performance."}},"description":"Configuration settings and credentials required to integrate with Salesforce, enabling seamless data synchronization and interaction with Salesforce APIs. This property typically includes authentication details, API endpoints, and any necessary parameters for establishing a secure connection to a Salesforce instance.\n\n**Field behavior**\n- Holds all necessary information to authenticate and communicate with Salesforce services.\n- Used to configure API calls for data retrieval, updates, and other Salesforce operations.\n- May include nested objects or fields such as client ID, client secret, access tokens, instance URLs, and API versions.\n\n**Implementation guidance**\n- Ensure sensitive information like client secrets and access tokens are securely stored and transmitted.\n- Validate the presence and correctness of required fields before attempting Salesforce integration.\n- Support token refresh mechanisms if applicable to maintain session validity.\n- Allow configuration flexibility to support different Salesforce environments (e.g., non-production, production).\n\n**Examples**\n- An object containing OAuth credentials: client_id, client_secret, refresh_token, and instance_url.\n- Configuration specifying API version and endpoint URLs.\n- JSON structure with nested authentication and connection parameters.\n\n**Important notes**\n- Proper error handling should be implemented for authentication failures or API call errors.\n- Salesforce API limits and quotas should be considered when designing integration logic.\n- Secure handling of credentials is critical to prevent unauthorized access.\n- The structure and required fields may vary depending on the Salesforce API version and authentication method used.\n\n**Dependency chain**\n- Dependent on Salesforce authentication mechanisms (OAuth 2.0, username-password flow, etc.).\n- Relies on network connectivity to Salesforce endpoints.\n- May depend on external libraries or SDKs for Salesforce API interaction.\n\n**Technical details**\n- Typically involves OAuth 2.0 tokens or username-password credentials.\n- Uses HTTPS for secure communication with Salesforce REST or SOAP APIs.\n- May include refresh token logic to maintain long-term access.\n- Supports configuration of API versioning to align with Salesforce API changes."},"ebay":{"type":"object","properties":{"appId":{"type":"string","description":"The unique identifier assigned to an application registered with the eBay developer program. This ID is used to authenticate API requests and associate them with a specific application.\n\n**Field behavior**\n- Must be included in API requests to identify the calling application.\n- Typically a string consisting of alphanumeric characters.\n- Used to track usage and enforce rate limits for the application.\n- Required for accessing most eBay APIs.\n\n**Implementation guidance**\n- Obtain the appId by registering your application on the eBay Developer Program portal.\n- Keep the appId confidential to prevent unauthorized use.\n- Include the appId in the request headers or parameters as specified by the API documentation.\n- Validate the appId format before sending requests to avoid errors.\n\n**Examples**\n- \"12345678-1234-1234-1234-123456789abc\"\n- \"MyEbayAppID2024\"\n- \"APP-9876543210\"\n\n**Important notes**\n- The appId is different from other eBay credentials such as client ID or client secret.\n- Using an invalid or expired appId will result in authentication errors.\n- Do not share your appId publicly to protect your application's security.\n\n**Dependency chain**\n- Depends on successful registration with the eBay Developer Program.\n- Used in conjunction with other authentication credentials like OAuth tokens.\n- Required before making authorized API calls.\n\n**Technical details**\n- Typically a UUID or a unique string assigned by eBay.\n- Passed as part of HTTP headers or query parameters depending on the API.\n- Used by eBay servers to identify and authenticate the application making the request."},"devId":{"type":"string","description":"The unique identifier assigned to a developer or development team by eBay. This ID is used to authenticate and track API usage associated with the developer's applications. It ensures that API requests are properly attributed and helps manage access permissions and rate limits.\n\n**Field behavior**\n- Must be included in API requests requiring developer authentication.\n- Used to identify the source of API calls.\n- Typically remains constant for a given developer or development team.\n- Should be kept confidential to prevent unauthorized use.\n\n**Implementation guidance**\n- Obtain the devId by registering as a developer on the eBay Developer Program portal.\n- Include the devId in all relevant API request headers or parameters as specified by eBay.\n- Store the devId securely in your application environment.\n- Do not expose the devId in client-side code or public repositories.\n\n**Examples**\n- \"1234567890\"\n- \"dev_abcdef123456\"\n- \"9876543210\"\n\n**Important notes**\n- The devId is distinct from other eBay identifiers such as appId, certId, or auth tokens.\n- Misuse or leakage of the devId can lead to unauthorized API access.\n- Changes to the devId require updating all applications using it.\n- Ensure compliance with eBay's developer policies when using the devId.\n\n**Dependency chain**\n- Often used alongside appId and certId for full API authentication.\n- May be required before obtaining OAuth tokens or other credentials.\n- Linked to developer account settings and permissions on eBay.\n\n**Technical details**\n- Typically a string of alphanumeric characters.\n- Assigned by eBay upon developer registration.\n- Used in API request headers or query parameters depending on the API endpoint.\n- Validated by eBay servers to authorize API access."},"certId":{"type":"string","description":"The eBay certificate ID value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `certId_crypt`/`certId_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext certificate ID value here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."},"ruName":{"type":"string","description":"The Russian name associated with the eBay entity, typically used for localization and display purposes in Russian-language contexts. This field contains the name as it should appear to Russian-speaking users, ensuring proper representation and cultural relevance.\n\n**Field behavior**\n- Represents the localized name in Russian.\n- Used primarily for display in Russian language interfaces.\n- Should accurately reflect the entity's name in Russian script.\n- May be omitted if no Russian localization is available.\n\n**Implementation guidance**\n- Ensure the name is correctly translated and culturally appropriate.\n- Use Cyrillic characters as per Russian language standards.\n- Validate the string for encoding compatibility (UTF-8).\n- Update this field when the entity's Russian name changes.\n\n**Examples**\n- \"Электроника\" (Electronics)\n- \"Мода\" (Fashion)\n- \"Дом и сад\" (Home and Garden)\n\n**Important notes**\n- This field is optional if the entity does not have a Russian localization.\n- Avoid transliterations; use proper Russian language terms.\n- Consistency with other localized names is important for user experience.\n\n**Dependency chain**\n- May depend on the primary name or English name for context.\n- Used in conjunction with other localized name fields for multi-language support.\n\n**Technical details**\n- Data type: string.\n- Character encoding: UTF-8.\n- Maximum length should conform to system constraints for name fields."}},"description":"Contains configuration settings and credentials specific to eBay integration within the application. This property manages parameters required to connect, authenticate, and interact with eBay's APIs and services.\n\n**Field behavior**\n- Holds all necessary eBay-related configuration details.\n- Used to enable and customize eBay platform interactions.\n- May include API keys, tokens, endpoint URLs, and feature toggles.\n- Supports dynamic updates to eBay integration settings without redeploying the application.\n\n**Implementation guidance**\n- Securely store sensitive information such as API credentials.\n- Validate the presence and correctness of required fields before making API calls.\n- Support environment-specific configurations for different environments.\n- Ensure compatibility with the latest eBay API versions.\n- Provide clear error handling and logging for eBay-related operations.\n\n**Examples**\n- API key and secret for eBay developer account.\n- OAuth tokens for user authentication with eBay.\n- URLs for eBay REST or Trading API endpoints.\n- Flags to enable or disable specific eBay features like inventory management or order processing.\n\n**Important notes**\n- Credentials must be kept confidential and never exposed in client-side code.\n- Regularly update tokens and keys to maintain uninterrupted service.\n- Comply with eBay's API usage policies and rate limits.\n- Changes to this configuration may affect live eBay transactions and listings.\n\n**Dependency chain**\n- Dependent on eBay developer account and API access permissions.\n- Interacts with authentication modules to manage tokens.\n- Works alongside order management and inventory systems for synchronization.\n- May depend on network connectivity and proxy settings for API calls.\n\n**Technical details**\n- Typically structured as a nested object containing keys like clientId, clientSecret, accessToken, refreshToken, and apiEndpoints.\n- May include metadata such as token expiration timestamps and scopes.\n- Supports serialization and secure storage mechanisms.\n- Designed to be extensible for future eBay API features and versions."},"amazonmws":{"type":"object","properties":{"accessKeyId":{"type":"string","description":"The Access Key ID is a unique identifier assigned to your Amazon MWS (Marketplace Web Service) account, used to authenticate API requests. It acts as a public credential that, together with the Secret Access Key, allows secure access to Amazon MWS services. This key is essential for programmatic interaction with Amazon's seller APIs, enabling operations such as order retrieval, inventory management, and report generation.\n\n**Field behavior**\n- Must be a valid, active Access Key ID issued by Amazon.\n- Used in conjunction with the Secret Access Key to sign API requests.\n- Should be kept confidential to prevent unauthorized access.\n- Typically a 20-character alphanumeric string.\n\n**Implementation guidance**\n- Retrieve the Access Key ID from your AWS Management Console or Amazon MWS developer account.\n- Ensure the Access Key ID corresponds to the correct AWS user with appropriate permissions.\n- Do not hard-code the key in publicly accessible code repositories.\n- Rotate keys periodically to maintain security best practices.\n\n**Examples**\n- \"AKIAIOSFODNN7EXAMPLE\"\n- \"ABCD1234EFGH5678IJKL\"\n- \"A1B2C3D4E5F6G7H8I9J0\"\n\n**Important notes**\n- The Access Key ID alone is insufficient for authentication; it must be paired with the Secret Access Key.\n- Exposure of the Access Key ID and Secret Access Key can lead to unauthorized access and potential data breaches.\n- If compromised, immediately revoke and regenerate the keys via the AWS console.\n- Access Key IDs are case-sensitive.\n\n**Dependency chain**\n- Requires a corresponding Secret Access Key for request signing.\n- Must be associated with an AWS IAM user or role with Amazon MWS permissions.\n- Used alongside other credentials such as Seller ID and MWS Auth Token for full API access.\n\n**Technical details**\n- Format: 20-character alphanumeric string.\n- Used in the AWS Signature Version 2 or 4 signing process.\n- Included in the HTTP headers or query parameters of API requests.\n- Validated by Amazon MWS servers to authorize API calls."},"secretKey":{"type":"string","description":"The Amazon MWS secret key value used for authentication.\n\nThis is the value you provide to configure or update the iClient. Internally, integrator.io stores this value encrypted at rest (for example as `secretKey_crypt`/`secretKey_salt` fields in the underlying model), and API responses typically return a masked value (e.g., `\"******\"`) when a value is already set.\n\n**Implementation guidance**\n- Provide the plaintext secret key value here to set/update it.\n- To keep the existing value unchanged during an update, omit this field (or keep `\"******\"` as-is if returned)."}},"description":"Configuration settings required to integrate with the Amazon Marketplace Web Service (Amazon MWS) API, enabling programmatic access to Amazon seller account data and operations. This includes credentials and parameters necessary for authentication, authorization, and interaction with various Amazon MWS endpoints.\n\n**Field behavior**\n- Contains all necessary authentication credentials such as Access Key ID, Secret Access Key, Seller ID, and MWS Auth Token.\n- May include configuration options like marketplace IDs, region settings, and API version.\n- Used to establish secure and authorized communication with Amazon MWS services.\n- Typically required for operations such as order retrieval, inventory management, and report generation.\n\n**Implementation guidance**\n- Ensure all credentials are stored securely and transmitted over encrypted channels.\n- Validate the presence and correctness of all required fields before attempting API calls.\n- Support refreshing or updating credentials as needed to maintain uninterrupted access.\n- Handle error responses gracefully, including authentication failures or permission issues.\n- Follow Amazon MWS best practices and rate limits to avoid throttling.\n\n**Examples**\n- Access Key ID: \"AKIAIOSFODNN7EXAMPLE\"\n- Secret Access Key: \"1234567890abcdef1234567890abcdef12345678\"\n- Seller ID: \"A1XEXAMPLE123\"\n- MWS Auth Token: \"amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE\"\n\n**Important notes**\n- Amazon MWS is being succeeded by the Selling Partner API (SP-API); consider migration plans.\n- Credentials must be kept confidential to prevent unauthorized access.\n- API access is subject to Amazon’s terms of service and usage policies.\n- Proper error handling is critical to manage API rate limits and service disruptions.\n\n**Dependency chain**\n- Requires valid Amazon seller account with MWS access enabled.\n- Dependent on network connectivity to Amazon MWS endpoints.\n- May depend on other configuration properties such as marketplace identifiers.\n\n**Technical details**\n- Uses RESTful API calls with XML or JSON payloads.\n- Authentication is based on AWS Signature Version 2 or 4.\n- Supports multiple API sections including Orders, Reports, Feeds, and Products.\n- Requires timestamp synchronization to prevent request rejection."},"jwt":{"type":"object","description":"A JSON Web Token (JWT) used for securely transmitting information between parties as a JSON object. This token is typically used for authentication and authorization purposes, ensuring that the client has valid credentials to access protected resources. The JWT contains encoded header, payload, and signature sections that verify the token's integrity and authenticity.\n**Field behavior**\n- Must be a valid JWT string following the standard format: header.payload.signature.\n- Used to authenticate API requests and authorize access to specific endpoints.\n- Typically included in the Authorization header as a Bearer token.\n- Should have an expiration time to enhance security.\n**Implementation guidance**\n- Validate the JWT on the server side to ensure it is properly signed and not expired.\n- Use secure algorithms (e.g., RS256 or HS256) for signing the token.\n- Store sensitive information in the payload with caution, as JWTs can be decoded by clients.\n- Refresh tokens should be used to obtain new JWTs when the current one expires.\n**Examples**\n- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\n- eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJleGFtcGxlLmNvbSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJleHAiOjE2MjQ2MjQwMDB9.DQABCD1234abcd5678efgh9012ijkl3456mnop7890qrstuv\n**Important notes**\n- JWTs should be transmitted over secure channels (HTTPS) to prevent interception.\n- Do not store JWTs in insecure storage locations on the client side (e.g., localStorage) to avoid XSS attacks.\n- Always verify the token's signature and claims before granting access.\n- Be aware of token expiration and implement proper handling for expired tokens.\n**Dependency chain**\n- Depends on the authentication mechanism generating the JWT.\n- Requires a"}}},"Response":{"type":"object","description":"Complete iClient object as returned by the API.\n\n**Note:** iClient responses do not include `createdAt`, `deletedAt`, or\n`_userId`. The only timestamp returned is `lastModified`.","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the iClient."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the last modification (ISO 8601, UTC)."},"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration instance ID (only present for integration-app iClients)."},"_connectorId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration app ID (only present for integration-app iClients)."}},"required":["_id"]}]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/iClients/{_id}":{"put":{"summary":"Update an iClient","description":"Replaces an existing iClient configuration. All mutable fields must be\nprovided; omitted fields are reset to defaults.\n","operationId":"updateIClient","tags":["iClients"],"parameters":[{"in":"path","name":"_id","required":true,"schema":{"type":"string"},"description":"The unique identifier of the iClient to update"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"iClient updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}} ``` ## Delete an iClient > Deletes an iClient permanently. This operation cannot be undone.\ > \ > If the iClient is still referenced by a connection or other resource,\ > the API returns \`422\` with code \`delete\_not\_allowed\` and a message\ > identifying the referencing resource. Use the dependencies endpoint\ > to check before deleting.
```json {"openapi":"3.1.0","info":{"title":"iClients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/iClients/{_id}":{"delete":{"summary":"Delete an iClient","description":"Deletes an iClient permanently. This operation cannot be undone.\n\nIf the iClient is still referenced by a connection or other resource,\nthe API returns `422` with code `delete_not_allowed` and a message\nidentifying the referencing resource. Use the dependencies endpoint\nto check before deleting.\n","operationId":"deleteIClient","tags":["iClients"],"parameters":[{"in":"path","name":"_id","required":true,"schema":{"type":"string"},"description":"The unique identifier of the iClient to delete"}],"responses":{"204":{"description":"iClient deleted successfully (no response body)"},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}} ``` ## Partially update an iClient > Partially updates an iClient using JSON Patch (RFC 6902) operations.\ > \ > \*\*Whitelisted fields:\*\* only \`/oauth2/failPath\` can be patched. Attempting\ > to patch any other path (e.g. \`/name\`, \`/oauth2/clientId\`,\ > \`/oauth2/failValues\`) returns \`422\` with\ > \`"\ is not a whitelisted property"\`.\ > \ > The request body must be a JSON array of patch operations. Sending a\ > non-array body returns \`422\` with \`"invalid patch data"\`. An empty\ > array \`\[]\` is accepted and returns \`204\` with no changes applied.\ > \ > On success the API returns \*\*204 No Content\*\* with no response body. ```json {"openapi":"3.1.0","info":{"title":"iClients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/iClients/{_id}":{"patch":{"summary":"Partially update an iClient","description":"Partially updates an iClient using JSON Patch (RFC 6902) operations.\n\n**Whitelisted fields:** only `/oauth2/failPath` can be patched. Attempting\nto patch any other path (e.g. `/name`, `/oauth2/clientId`,\n`/oauth2/failValues`) returns `422` with\n`\" is not a whitelisted property\"`.\n\nThe request body must be a JSON array of patch operations. Sending a\nnon-array body returns `422` with `\"invalid patch data\"`. An empty\narray `[]` is accepted and returns `204` with no changes applied.\n\nOn success the API returns **204 No Content** with no response body.","operationId":"patchIClient","tags":["iClients"],"parameters":[{"in":"path","name":"_id","required":true,"schema":{"type":"string"},"description":"The unique identifier of the iClient"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["op","path"],"properties":{"op":{"type":"string","enum":["replace","add","remove"],"description":"The JSON Patch operation."},"path":{"type":"string","enum":["/oauth2/failPath"],"description":"JSON pointer to the field to modify. Only `/oauth2/failPath`\nis whitelisted."},"value":{"type":"string","description":"The new value for the field. Required for `replace` and `add`\noperations; omit for `remove`."}}}}}}},"responses":{"204":{"description":"Patch applied successfully (no response body)"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}} ``` ## List dependencies of an iClient > Returns the set of resources that depend on the specified resource.\ > The response is an object whose keys are dependent-resource types\ > (e.g. \`flows\`, \`imports\`) and whose values are arrays of dependency\ > entries.\ > \ > AI guidance:\ > \- An empty object \`{}\` means no other resources depend on the target.\ > This is also returned for a well-formatted but nonexistent id. ```json {"openapi":"3.1.0","info":{"title":"iClients","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"DependencyResponse":{"type":"object","description":"Map of dependent-resource types to arrays of dependency entries.\nKeys are plural resource type strings (e.g. `flows`, `imports`,\n`connections`). An empty object `{}` means no dependents.\n","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DependencyEntry"}}},"DependencyEntry":{"type":"object","description":"A single resource that depends on the queried resource.","properties":{"id":{"type":"string","description":"Unique identifier of the dependent resource."},"name":{"type":"string","description":"Display name of the dependent resource."},"paths":{"type":"array","description":"JSON-path-style pointers within the dependent resource's document\nthat reference the target resource.\n","items":{"type":"string"}},"accessLevel":{"type":"string","description":"The caller's access level on the dependent resource."},"dependencyIds":{"type":"object","description":"Map of resource types to arrays of ids that this dependent\nresource references on the target. Keys are singular or plural\nresource type strings; values are arrays of id strings.\n","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["id","name","paths","accessLevel","dependencyIds"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/iClients/{_id}/dependencies":{"get":{"operationId":"listIClientDependencies","tags":["iClients"],"summary":"List dependencies of an iClient","description":"Returns the set of resources that depend on the specified resource.\nThe response is an object whose keys are dependent-resource types\n(e.g. `flows`, `imports`) and whose values are arrays of dependency\nentries.\n\nAI guidance:\n- An empty object `{}` means no other resources depend on the target.\n This is also returned for a well-formatted but nonexistent id.","parameters":[{"name":"_id","in":"path","required":true,"description":"Resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Dependency map. Keys are resource-type strings; values are arrays\nof dependency entries. Returns `{}` when no dependents exist.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependencyResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.celigo.com/api/api-reference/iclients.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.