Configure and rotate Flex Web Service access

Flex Web Service access has two manually managed identifiers with different roles:

• the token authorizes Flex Web Service requests and expires; and
• the Query ID selects a saved template whose account scope and output schema were configured separately.

Neither value is a TWS login, Client Portal password, OAuth token, nor socket API credential. TWS and IB Gateway do not need to be running for this HTTPS reporting workflow.

Enable the service and capture the token

The current official token configuration guide documents this manual Client Portal sequence:

1. Open Reporting, then Flex Queries.
2. Open Flex Web Service Configuration.
3. Enable Flex Web Service Status and save; Client Portal displays an initial Current Token.
4. To set a deliberate lifetime or IP restriction, open Generate A New Token.
5. Select a lifetime between six hours and one year and, optionally, a valid source IP.
6. Generate the replacement. The separate official Client Portal Flex Web Service guide says this invalidates the prior token.
7. Capture only the final Current Token directly into an approved secret store.

The Client Portal guide also documents that, in a linked-account structure, the token may be visible only from the master account. Its retrieval scope still depends on which accounts were included when the saved query was created. Do not work around a missing configuration panel by copying a token from a different user or account structure.

Never paste the token into a ticket, shell history, source file, screenshot, CI log, URL shown in an exception, or documentation example. A neutral configuration contract is enough:

FLEX_WEB_SERVICE_TOKEN=<secret-store reference>
FLEX_QUERY_ID=<sensitive configuration reference>
FLEX_TEMPLATE_REVISION=activity-v1
FLEX_TOKEN_EXPIRES_AT=<operator-recorded UTC timestamp>
FLEX_EXPECTED_EGRESS_IP=<approved public egress IP, if restricted>

These are names and placeholders, not example credentials.

Bind the Query ID to the reviewed template

The official Query ID guide places the identifier in the saved query's Info popover. Capture it only after confirming the intended query name, report family, selected account set, and reviewed template revision.

Store the Query ID as sensitive configuration even though it is not sufficient without the token. Deploy these values as one configuration unit:

Value	Change trigger	Validation boundary
Token reference	Rotation or expiry change	Secret exists; never print its value.
Query ID reference	New or replaced saved query	Matches the intended query and account selection.
Template revision	Any section, field, ordering, period, scope, or format change	Returned XML must match the consumer contract.
Expiration timestamp	Token generation or rotation	Alert before expiry; reject already expired configuration.
Expected egress IP	Network or restriction change	Compare through an approved operational check, not a token-bearing test URL.

Repository operational policy: deploy these independently managed values as one reviewed configuration unit. Regardless of whether each identifier is accepted separately, treat a report from an unexpected account scope or schema as a configuration failure, not as acceptable data. This policy follows from the official account-selection boundary and from treating template changes as consumer schema changes; it is not an additional IBKR protocol guarantee.

Plan rotation as a coordinated cutover

The official Client Portal Flex Web Service guide says that Generate A New Token invalidates the prior token. IBKR does not document a dual-token overlap window. Repository operational policy: treat rotation as a coordinated no-overlap cutover.

Use this operational sequence:

1. Inventory every consumer of the current secret reference.
2. Pause new report generation or establish a controlled maintenance window.
3. Choose and record the new expiration and, if used, the public egress IP restriction.
4. Generate the token once and write it directly to the secret store.
5. Atomically update the consumers' secret reference or version.
6. Run one bounded, token-redacted health request from the authorized network.
7. Resume scheduling only after the response is classified.
8. Record the rotation time, expiry, operator, consumer set, and outcome without recording the token or a token-bearing URL.

Use rotation only for an intended credential cutover or a classified credential failure. Repository operational policy: do not generate another token in response to an unclassified request failure, because generation invalidates the credential still used by other consumers. The request-and-polling guide will define transport and unresolved-report outcomes.

Apply IP restriction to the actual requester

The official guide says token generation can restrict which IPs make requests, but it does not define application network topology. Repository network inference: configure the restriction for the stable public source IP presented by the authorized runtime. For a hosted consumer, that is normally its public NAT or proxy egress address, not its private container address, TWS host, or an operator laptop.

Before enabling the restriction, confirm that every authorized runtime uses the approved stable egress path. If egress is dynamic, first provision stable egress or leave the optional restriction unset under an explicitly reviewed security decision. A successful request from an operator workstation does not validate a production worker's source IP.

Recognize credential-configuration failures

The current official Flex error-code reference assigns these server-side failures to both /SendRequest and /GetStatement:

Error code	Official meaning	Repository operational response (inference)
1011	Service account is inactive.	Verify that Flex Web Service Status is enabled for the correct user/account structure; do not retry in a tight loop.
1012	Token has expired.	Rotate through the controlled cutover and update the recorded expiry.
1013	IP restriction.	Verify the configured allowlisted IP and the requester's actual public egress before changing either.

The codes and meanings above are official; the response column is repository operational policy. Classify by the returned Flex error code, not by matching prose alone. Blind retries do not remediate the named service-state, expiry, or IP configuration. Keep the token and complete request URL out of logs; retain the error code and a sanitized configuration identity. The later polling design will define additional attempt and correlation metadata.

Setup handoff checklist

• Flex Web Service is enabled under the intended user and account structure.
• The token is stored only in the approved secret system.
• Expiration is recorded in UTC and monitored before the selected deadline.
• Any IP restriction matches every production requester's stable public egress.
• Query ID matches the reviewed saved-query name, account selection, and report family.
• Query ID is bound to a non-secret template revision.
• Rotation ownership and the no-overlap cutover procedure are documented.
• Logs and alerts contain no token or token-bearing URL.
• Errors 1011, 1012, and 1013 route to configuration remediation rather than automatic retry.

Next, request and retrieve a Flex report with the version 3 /SendRequest and /GetStatement lifecycle without exposing either identifier in observability.