Working with GraphQL APIs in Falcon Foundry

You want to call a GraphQL API from your Falcon Foundry app, and you’ve just discovered that API integrations only accept OpenAPI specs. GraphQL endpoints don’t have OpenAPI specs. So what do you do?

The answer depends on whose GraphQL endpoint you’re calling. If it’s a Falcon API like Identity Protection, you write a Python function and let FalconPy handle authentication for you. If it’s a third-party GraphQL API, you still write a function, but you manage the credentials yourself. This post walks through both paths, with a real example you can deploy today.

When to Use API Integrations vs. Falcon Foundry Functions

Falcon Foundry’s API integrations parse OpenAPI specs to configure authentication, map request/response schemas, and share endpoints with Falcon Fusion workflows. They’re the right choice when you’re working with REST APIs because they require less code and the platform manages credentials at install time.

GraphQL endpoints don’t produce OpenAPI specs. If the API you need speaks GraphQL, you need a Falcon Foundry function regardless of where that API lives.

The rest of this post focuses on the second and third rows.

Why foundry-js Doesn’t Cover GraphQL APIs

The @crowdstrike/foundry-js library is the JavaScript SDK that connects your Falcon Foundry UI to the Falcon platform. It ships typed clients for Falcon REST APIs: alerts, detects, devices, incidents, remote-response, workflows, and about a dozen others. These clients are generated from Falcon’s OpenAPI specs. Identity Protection’s timeline and notifications data is exposed only through GraphQL, so there’s no foundry-js client for it.

If you’re building a UI page that needs Identity Protection data, the path is: write a Python function that calls FalconPy’s GraphQL method, then invoke that function from your UI via falcon.cloudFunction(). This is the same pattern you’d use for any backend logic that the UI needs to call.

Calling Falcon’s GraphQL Endpoint with FalconPy

FalconPy’s service classes handle authentication automatically inside Falcon Foundry functions, so you instantiate the client with zero parameters. The platform injects credentials at runtime based on the OAuth scopes declared in your manifest.yml.

The core pattern boils down to three lines:

from falconpy import IdentityProtection

falcon = IdentityProtection()
response = falcon.graphql(query=idp_query, variables=variables)

The identity-graphql:write scope in your manifest is what grants the function permission to call this endpoint. GraphQL requests go out as HTTP POSTs, so the endpoint requires the :write scope even when your query only reads data. If you prefer writing functions in the browser, the Python editor auto-detects the required scopes when you import a FalconPy service class.

Example: Query Identity Protection Notifications with GraphQL

The foundry-sample-idp-notifications app monitors identity protection notifications, domain controller health, and connector status. Its functions/monitoring/main.py file demonstrates how to build a GraphQL query with fragments and variables, call the endpoint, and extract the results. It also includes error handling, input validation, and a companion endpoint that reports domain controller sensor status. That second endpoint reuses the same IdentityProtection() client but calls its REST methods (query_sensors, get_sensor_details) instead of GraphQL, a nice reminder that one FalconPy service class can expose both.

The GraphQL query fetches timeline events filtered by category, status, and start time:

idp_query = '''
query ($categories: [TimelineEventCategory!], $open: Boolean, $startTime: DateTimeInput) {
  timeline(categories: $categories, first: 1000, open: $open, sortOrder: DESCENDING, startTime: $startTime) {
    ...TimelineNotificationEventDetails
  }
}

fragment TimelineNotificationEventDetails on TimelineEventConnection {
  edges {
    cursor
    node {
      eventType
      timestamp
      startTime
      endTime
      ... on TimelineNotificationEvent {
        state {
          dismissed
          resolved
        }
      }
      ... on TimelineDomainRemovalEvent {
        domain
      }
      ... on TimelineDomainControllerNotificationEvent {
        domainControllerEntity {
          ...MinimalEntityDescriptor
        }
      }
      ... on TimelineUncoveredDomainControllerEvent {
        domain
      }
      ... on TimelineConnectorFailureEvent {
        connectorType
        providerType
        connectorStatus
        errorDetails{
          message
        }
      }
    }
  }
}

fragment MinimalEntityDescriptor on Entity {
  entityId
  primaryDisplayName
  secondaryDisplayName
  archived
}
'''

The function constructs variables from the incoming request, calls falcon.graphql(), and extracts events from the response:

variables = {
    'categories': categories,
    'startTime': duration,
    'open': notification_status
}

falcon = IdentityProtection()
response = falcon.graphql(query=idp_query, variables=variables)

# Extract events from the response
events = []
timeline_edges = response.get("body", {}).get("data", {}).get("timeline", {}).get("edges", [])
for edge in timeline_edges:
    if edge and "node" in edge:
        events.append(edge["node"])

The app’s manifest.yml declares seven OAuth scopes including identity-graphql:write and identity-timeline:read. These scopes determine what the function can access at runtime.

Calling Third-Party GraphQL APIs from Falcon Foundry Functions

For third-party GraphQL APIs (GitHub, Snyk, or any service that exposes a GraphQL endpoint), there’s no FalconPy equivalent. You make a standard HTTP POST with the requests library and pass the query in the JSON body.

Here’s a minimal example calling GitHub’s GraphQL API from a Foundry function:

import os
import requests

def query_github_graphql(query, variables=None):
    response = requests.post(
        "https://api.github.com/graphql",
        json={"query": query, "variables": variables or {}},
        headers={"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}"}
    )
    return response.json()

The credential (GITHUB_TOKEN) comes from an environment variable defined in your manifest. This works, but it introduces a credential management concern that doesn’t exist with FalconPy.

Security Considerations for GraphQL Credentials in Falcon Foundry

If you’re only calling Falcon GraphQL endpoints with FalconPy, you have zero credential exposure. The platform manages authentication, nothing is stored in your code or environment variables, and nothing appears in app exports. You can stop reading this section.

For third-party GraphQL APIs, credentials live in environment variables or directly in function code. Anyone with the App Developer or Falcon Administrator role can export the app and read these values in plain text. Credentials provided at install time for API integrations are protected from export, but since GraphQL endpoints can’t use API integrations, that protection doesn’t apply here. App exports are not currently logged in the customer-facing audit log, so there’s no way to detect when someone exports an app containing your credentials.

Three options to reduce the risk: scope the credential to the minimum required permissions (read-only if the API supports it), restrict the App Developer role in your tenant to limit who can export apps, and prefer OAuth client credentials with token expiry over static API keys when the third-party service supports it. Short-lived tokens limit the window of exposure if they end up somewhere they shouldn’t.

Start Building with GraphQL and Falcon Foundry

If you need Identity Protection data in your Falcon Foundry app today, clone the sample and deploy it. The function pattern shown here works for any Falcon API that exposes a GraphQL endpoint.

git clone https://github.com/CrowdStrike/foundry-sample-idp-notifications
cd foundry-sample-idp-notifications
foundry apps deploy

For more on Falcon Foundry functions and API integrations, see the following Tech Hub articles:

• Dive into Falcon Foundry Functions with Python
• Getting Started with foundry-js using the Foundry-JS Demo App
• Build API Integrations with Falcon Fusion HTTP Actions

You might also find these resources useful:

• FalconPy documentation
• Falcon Foundry functions documentation

What GraphQL APIs are you integrating with your Falcon deployment? Join the Foundry Developer Community and share what you’re building. If you’re starting from scratch, Claude Code can scaffold a Foundry app for you.