Try JFrog
Guides
Contact SupportTry JFrog
  1. Integrations
  2. JFrog OneModel GraphQL

Platform Federation OneModel GraphQL

Platform Federation is available on Enterprise+ subscriptions only. Confirm that a Platform Federation is defined in your organization before you send a request to this API.

You can use this OneModel GraphQL API to query the Grid service that maintains the multisite Platform Federation topology, and to monitor the sync status of entities as they replicate across that topology. This API follows the OneModel GraphQL conventions and supports pagination, filtering, and cross queries.

Prerequisites

  • You must submit these GraphQL API requests to the Main Site of the Platform Federation. This is the site on which the Platform Federation was defined and is monitored.

  • The Main Site must run the following versions: JFrog Access 7.183.2 or later. Grid service 1.193 or later.

  • Specify the token audience as wildcard *@*. The Grid service doesn't require a service-specific audience scope.

  • Platform Admin privileges. Every GraphQL query requires an admin-scoped access token. Non-admin tokens are rejected before the query executes.

  • These GraphQL API requests report on an active Platform Federation. Use this API after you have defined a Platform Federation.

Subgraph Entities

The Grid subgraph exposes two related groups of entities:

  • Topology: A GridTopology represents the set of JFrog Platform Deployment (JPD) sites connected in a Platform Federation. A Platform Federation has exactly one topology. Each connected site is a GridTopologySite, which describes its geographic location including city and country code, and its federation status: CONNECTED, DISCONNECTED, PARTIALLY_CONNECTED, or PENDING_REMOVAL.
  • Monitoring: Within a topology, the Grid service tracks the sync status of entities as they replicate across sites. Examples include users, groups, and project groups. You can query aggregated sync counts per entity type, search for individual entities by status, or drill into the full site-to-site sync detail for a single entity.

Entity Type Keys

Monitoring queries accept an entityType of type GridEntityTypeKey. The valid values are: access.projects, access.environments, access.roles, access.groups, access.users, access.tokens, access.permissions, access.projectUsers, access.projectGroups, access.projectResources

Entity Type Keys

Monitoring queries accept an entityType of type GridEntityTypeKey. The following values are defined for basic project, user, and permission entities:

  • access.groups, access.users
  • access.permissions
  • access.tokens
  • access.projects, access.projectUsers, access.projectGroups, access.projectResources
  • access.environments
  • Access.roles

Additional GridEntityTypeKey values define entities for JFrog security, governance, and other features integrated with the Platform Federation.

Common Use Cases

Retrieve a Topology and Its Connected Sites

Use this query to see all sites in your Platform Federation, along with each site's location and current federation status. This is typically the first request you make to discover which sites participate in a given topology.

GraphQL

query GetTopology {
  grid {
    getTopology(key: "<TOPOLOGY_KEY>") {
      key
      name
      description
      sites {
        name
        isCurrent
        location {
          city
          countryCode
        }
        status {
          code
          description
        }
      }
    }
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"{ grid { getTopology(key: \"<TOPOLOGY_KEY>\") { key name description sites { name isCurrent location { city countryCode } status { code description } } } } }"}'

Find Entities With a Failed Sync

Use this query to list entities of a given type that failed to sync somewhere in your topology. This lets you triage them without pulling every entity. Results are paginated. Use pageInfo.endCursor as the after value to fetch the next page.

GraphQL

query FailedUserSyncs {
  grid {
    searchMonitoringEntities(
      where: {
        topologyKey: "<TOPOLOGY_KEY>"
        entityType: "access.users"
        status: FAILED
      }
      first: 20
    ) {
      edges {
        node {
          entityId
          status
          targets {
            sourceSiteName
            targetSiteName
            status
            statusDescription
          }
        }
      }
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"{ grid { searchMonitoringEntities(where: { topologyKey: \"<TOPOLOGY_KEY>\", entityType: \"access.users\", status: FAILED }, first: 20) { edges { node { entityId status targets { sourceSiteName targetSiteName status statusDescription } } } totalCount pageInfo { hasNextPage endCursor } } } }"}'

The status argument is required. Valid status values are ALL, FAILED, IN_PROGRESS, and SYNCED.

A healthy topology has no failed entities, so this query legitimately returns an empty edges list with totalCount: 0. To confirm monitoring, run the summary report described in Review Sync Counts Across All Entity Types, or swap status: FAILED for status: SYNCED.

Review Sync Counts Across All Entity Types

Use this query as the dashboard overview: it returns one row per entity type with aggregated counts, so you can see at a glance where sync problems are concentrated before drilling in. Unlike the entity searches, it needs no entityType. It reports every type the Grid service tracks.

GraphQL

query MonitoringSummary {
  grid {
    searchMonitoringEntitySummaries(
      where: { topologyKey: "<TOPOLOGY_KEY>" }
      orderBy: [{ field: ENTITY_TYPE, direction: ASC }]
      first: 20
    ) {
      edges {
        node {
          entityType
          counts {
            failed
            inProgress
            synced
          }
        }
      }
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"{ grid { searchMonitoringEntitySummaries(where: { topologyKey: \"<TOPOLOGY_KEY>\" }, orderBy: [{ field: ENTITY_TYPE, direction: ASC }], first: 20) { edges { node { entityType counts { failed inProgress synced } } } totalCount pageInfo { hasNextPage endCursor } } } }"}'

List Successfully Synced Entities

Use this query to confirm a specific entity type is replicating correctly, or to pick an entityId for a Return Full Sync Detail for a Single Entity query.

GraphQL

query SyncedUsers {
  grid {
    searchMonitoringEntities(
      where: {
        topologyKey: "<TOPOLOGY_KEY>"
        entityType: "access.users"
        status: SYNCED
      }
      first: 20
    ) {
      edges {
        node {
          entityId
          status
        }
      }
      totalCount
    }
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"{ grid { searchMonitoringEntities(where: { topologyKey: \"<TOPOLOGY_KEY>\", entityType: \"access.users\", status: SYNCED }, first: 20) { edges { node { entityId status } } totalCount } } }"}'

Return Full Sync Detail for a Single Entity

Use this query once you've identified an entity of interest, for example from the previous query, and need the complete site-to-site sync breakdown, including the finer-grained PENDING and SENT states that aren't shown in list or summary results.

GraphQL

query GetEntitySyncDetail {
  grid {
    getMonitoringEntity(
      topologyKey: "<TOPOLOGY_KEY>"
      entityType: "access.users"
      entityId: "<ENTITY_ID>"
    ) {
      entityId
      status
      targets {
        sourceSiteName
        targetSiteName
        status
        statusDescription
        modifiedAt
      }
    }
  }
}

Executing the Query

curl --location -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  https://<YOUR_JFROG_DOMAIN>/onemodel/api/v1/graphql \
  -d '{"query":"{ grid { getMonitoringEntity(topologyKey: \"<TOPOLOGY_KEY>\", entityType: \"access.users\", entityId: \"<ENTITY_ID>\") { entityId status targets { sourceSiteName targetSiteName status statusDescription modifiedAt } } } }"}'

Updated about 2 hours ago

Did this page help you?