GraphQL connection (Early Access)
The GraphQL connection represents a single GraphQL endpoint, including the URL, the authentication method used to reach it, and the HTTP behavior applied to every request. If you have multiple endpoints — a production API and a sandbox API, or two different GraphQL services — configure a separate connection for each, then pair each connection with the operations that belong to it.
Connection tab
Endpoint
| Field | Description |
|---|---|
| GraphQL Endpoint URL | The URL of the GraphQL endpoint, for example https://api.example.com/graphql. Every query and mutation, and the introspection call made during import and Test Connection, is sent as an HTTP POST to this URL. Surrounding whitespace is ignored. Required. |
| Authentication Type | The authentication method used for the endpoint. Select None to send no authentication header — use this together with Custom Headers when the API expects an API key or a static token. Select OAuth 2.0 to use the client credentials flow, where the platform/runtime obtains and refreshes the access token and the connector sends it as a Bearer token. |
OAuth 2.0
These fields appear when Authentication Type is set to OAuth 2.0. The connector supports the client credentials grant type.
| Field | Description |
|---|---|
| Grant Type | Determines how the application obtains access tokens from the authorization server. Client Credentials is the supported value. |
| Client ID | The identifier issued to your application by the authorization server. |
| Credentials Assertion Type | Select Client Secret to authenticate with a shared password, or JWT Token to authenticate with a digitally signed token for key-based security. The default is Client Secret. |
| Client Secret | The secret issued alongside the client ID. Applies when Credentials Assertion Type is Client Secret. |
| Access Token URL | The URL your application calls to obtain access tokens from the authorization server. |
| Authorization Token URL | The endpoint used to interact with the resource owner and obtain an authorization grant. |
| Scope | The level of access requested for the token. Enter one or more space-separated values naming the permissions or resources the application needs. |
JWT token parameters
These fields apply when Credentials Assertion Type is set to JWT Token.
| Field | Description |
|---|---|
| Signature Algorithm | The cryptographic algorithm used to sign the JWT. Select an algorithm that matches your certificate type and security requirements, such as RS256 (RSA with SHA-256) or ES256 (ECDSA with P-256 curve and SHA-256). |
| Signature Key | The X.509 certificate component used to sign the JWT. |
| Issuer | Identifies the authority that issued the JWT. A case-sensitive URI or other unique identifier representing your application or authorization server. |
| Subject | Identifies the entity that is the subject of the JWT. A case-sensitive string, unique either within the issuer's context or globally, typically a user or entity identifier. |
| Audience | Identifies the intended recipients of the JWT. Enter one or more case-sensitive URIs or identifiers naming the services that should accept this token. Recipients must verify they are included in this list. |
| Expiration | Specifies when the token expires and must no longer be accepted for processing. |
| ID Claim Generator | Provides a unique identifier for the JWT. Select NONE to omit the jti claim, or UUID to generate a random unique identifier and send it as part of the JWT. |
| Key ID | An optional header parameter identifying which cryptographic key signed the JWT. Enter an identifier that corresponds to a specific key in your key set so recipients can select the correct key for signature verification. |
| X.509 Certificate SHA-256 Thumbprint | A base64url-encoded SHA-256 hash of the DER-encoded X.509 certificate used for signing. Encode the thumbprint to base64url format manually before entering it. |
note
GraphQL servers answer an authentication failure with HTTP 200 and an errors array rather than an HTTP 401 challenge, so the connector always sends the Bearer token preemptively on the first request rather than waiting to be challenged.
HTTP behavior
| Field | Description |
|---|---|
| Custom Headers | Additional HTTP headers included on every request, entered as name and value pairs. Use this to supply API-key style credentials when Authentication Type is None — for example X-Shopify-Access-Token, Authorization with a static bearer value, or X-API-Key — and to send any tenant, version, or trace headers the API requires. |
| Connection Timeout (ms) | HTTP connection timeout in milliseconds. Enter -1 for no timeout. The default is -1. |
| Read Timeout (ms) | HTTP read (socket) timeout in milliseconds. Enter -1 for no timeout. The default is -1. |
| Enable Connection Pooling | When selected, HTTP connections are pooled and reused across operation executions, which can improve performance under concurrent load by using resources more efficiently. When cleared, each execution opens its own connection. Selected by default. |
| Max Simultaneous Requests | The maximum number of simultaneous pooled connections at any time. The default is 20. If a value is not provided, or you set it to either -1 or 0, the default of 20 is used. Appears only when Enable Connection Pooling is selected. |
| Idle Timeout (s) | The maximum length of time, in seconds, that a pooled connection can remain idle before it is evicted. The default is 30. If a value is not provided, or you set it to either -1 or 0, the default of 30 is used. Appears only when Enable Connection Pooling is selected. |
Test Connection
Click Test Connection to verify the endpoint and credentials before you import an operation. The connector sends a minimal introspection query to the configured URL:
{"query":"{__schema{queryType{name}}}"}
The result is interpreted as follows:
| Endpoint response | Result |
|---|---|
| HTTP 2xx with schema data in the body | Succeeds. Full introspection is available. |
| HTTP 2xx with a well-formed GraphQL response but no schema data | Succeeds with a warning in the container log. The endpoint is reachable and the credentials are accepted, but introspection is restricted, so the import wizard generates a degraded profile. |
| An error whose message indicates introspection is disabled | Succeeds with a warning, for the same reason. |
| Any other GraphQL error, such as an authentication failure | Fails, and the endpoint's error message is shown. |
| A non-2xx HTTP status, a response that is not valid JSON, or a response with neither data nor errors | Fails. A response with neither data nor errors indicates the URL is probably not a GraphQL endpoint. |
A connection is required before you can browse: the import wizard calls the endpoint, so configure and test the connection first.
