Skip to main content
Version: Cloud

Omada Identity Graph API

Overview​

You can integrate access request workflows into external clients by using the Omada Identity Graph API. This capability is part of the Omada Everywhere initiative, which enables third parties to build clients for Omada access processes.

info

The Graph API uses GUIDs (Globally Unique Identifiers) for all entity references, not integer IDs. When a query or mutation requires an ID field, you must provide a GUID, for example, cf12e9f1-1cf8-4a75-b189-26a0677fdc01.

You can access the full API reference, including queries, mutations, types, arguments, and field-level descriptions, through schema introspection or the GraphiQL explorer. See Exploring the Schema.

tip

To view the latest supported changes, see the Changelog.

Authentication and impersonation​

The Omada Identity Graph API applies the same authentication level rules as the standard Omada Identity session model. Authentication levels determine which user group memberships apply to a session.

note

See the Impersonation and authentication levels for details, including:

  • When you use impersonation (via an Impersonation Service User), the authentication level is set to Low.
  • Only group memberships with an authentication level equal to or lower than the session level apply.

Exploring the schema​

The schema is the authoritative reference for the Graph API. You can use introspection or the GraphiQL browser to:

  • Explore available queries and mutations.
  • Review field-level descriptions.
  • Identify deprecated fields. You can do this directly in your browser or an HTTP client. To list all top-level query names and their deprecation status, run the following query:
{
  __schema {
    queryType {
      fields {
        name
        description
        isDeprecated
        deprecationReason
      }
    }
  }
}

GraphiQL provides the same information through a visual schema explorer.

Prerequisites​

  • Enable the new User Interface (UI).
  • Enable the GraphiQL browser page only in test or development environments - not in production.
info

Introspection must be enabled in the customer setting IntrospectionEnabled, in order to access GraphiQL.

Steps

  1. Open a ticket in Omada Service Desk to set the API Documentation UI Enabled customer setting to True.
  2. Enter the URL, for example: https://< instancename>.omada.cloud/ApiDoc.aspx?api=domain&version=X.X

Versioning and deprecation​

The Graph API is versioned. Older versions remain available for a transition period after a new major version is released. To see which versions are active on your instance, run:

query {
  versions {
    version
  }
}

Deprecated fields and queries​

Deprecated schema elements use the GraphQL @deprecated directive, which includes a machine-readable reason. Introspection queries and the GraphiQL schema explorer display this information. To check deprecated fields programmatically:

{
  __schema {
    queryType {
      fields {
        name
        isDeprecated
        deprecationReason
      }
    }
  }
}
warning

Do not build new integrations with deprecated fields. The deprecation reason indicates the recommended replacement.

info

You can also view deprecation notices in GraphiQL.

Known deprecations in the current release:​

Deprecated elementReplacementNotes
extendAccess2 mutationextendAccessSee inline schema description
accessRequest / accessRequests (v1.x)accessRequestComponentsv1.x queries are legacy
accessApprovalResourceAssignmentIdsaccessApprovalResourceAssignmentIdsTypo fix — the old misspelled name is retained but deprecated
hasChildrenInViolationviolationStatusThe field is deprecated and will be removed in GraphQL API version 4.0. Use the violationStatus field instead, which will include a value representing this state.

Examples​

The following examples show common workflows. For all available arguments and returned fields, see Exploring the Schema.

Create a resource-based access request​

  1. Fetch the available reasons, systems, and (optionally) a context for the requesting identity.
query {
  accessRequestComponents {
    reasons { id name }
    systems(
      filters: { name: { filterValue: "" } }
      sorting: { sortBy: NAME, sortOrder: DESCENDING }
      pagination: { page: 1, rows: 20 }
    ) {
      data { id name }
    }
    contexts(identityIds: "<identity-guid>") {
      id displayName
    }
  }
}
  1. Fetch the resource for the chosen system.
query {
  accessRequestComponents {
    resources(
      filters: {
        systemId: "<system-guid>"
        includeThirdPartyExcludedResources: false
      }
      pagination: { page: 1, rows: 20 }
    ) {
      data { id name }
    }
  }
}
  1. Submit the access request.
mutation {
  createAccessRequest(
    accessRequest: {
      identityResources: {
        identity: { id: "<identity-guid>" }
        resources: {
          id: "<resource-guid>"
          accountInfo: {
            accountTypeId: "<account-type-guid>"
            systemId: "<system-guid>"
          }
        }
      }
      context: "<context-guid>"
      reason: "Need additional access"
      validFrom: "2024-01-01T00:00:00Z"
      validTo: "2024-12-31T00:00:00Z"
    }
  )
}
  1. Check the request status.
{
  accessRequests(ids: ["<access-request-guid>"]) {
    id
    status { approvalStatus }
    resource { id name }
  }
}

Fetch approval survey questions and submit answers​

  • Fetch questions for pending approvals:
query {
  accessRequestApprovalSurveyQuestions(
    pagination: { page: 1, rows: 10 }
  ) {
    data {
      surveyObjectKey
      identity { displayName }
      resource { name }
      questions { id text }
    }
  }
}
  • Submit answers:
mutation {
  submitRequestQuestions(
    surveyObjectKey: "<survey-object-key-guid>"
    answers: [
      { questionId: "<question-guid>", answer: "Approved" }
    ]
  )
}

Policy checks in the approval context​

There are three policy checks available:

  • SoD policy check (soDPolicyCheck): evaluates segregation of duties conflicts using a RoPE calculation.
  • SAP risk analysis (sAPPolicyCheck): evaluates risks and SoD rules defined in SAP GRC.
  • Peer access analysis (peerReviewAccessPolicyCheck): compares peer access and returns a match percentage.
query {
  accessApprovalPolicyChecks {
    soDPolicyCheck {
      title
      description
      policyCheckResults {
        identity { displayName }
        resource { name }
        description
        status
      }
    }
  }
}
info

For more information on configuring policy checks, see Policy & Risk check feature.

References​

For further reference on GraphQL APIs and GraphiQL, see the following resources: