canonical: https://jentic.com/apis/googleapis.com/cloudidentity # Google Cloud Identity API Google Cloud Identity is the directory service that backs Google Workspace and standalone Cloud Identity tenancies. The API provisions and manages users, groups, group memberships, devices, inbound SAML SSO profiles, and policies. Agents can create groups, search the directory, lookup group keys, manage device enrollment, and configure inbound SSO assignments that delegate authentication to an external identity provider. It is the surface to use when an organisation needs to script directory operations rather than going through the Admin Console. ## For AI agents Provision and manage users, groups, devices, and inbound SAML SSO profiles in a Google Cloud Identity or Workspace tenancy. Useful for directory automation, group lifecycle, and SSO configuration. ## Scope Does not authenticate end users at runtime, manage Google Cloud IAM roles, or send email - use for directory, group, device, and inbound SSO configuration only. ## Capabilities - Create, list, search, and delete groups in the directory - Add or remove members from a group with specified roles - Look up a group by group key (email or external ID) - Enroll, list, and manage company-owned and BYOD devices - Configure inbound SAML SSO profiles for federated authentication - Assign inbound SSO profiles to organizational units or groups - List policies that apply to identity resources at the customer level ## Use cases ### Group Lifecycle Automation Identity teams use the Cloud Identity API to create and decommission groups in bulk based on HR system events. The flow creates a group, adds initial members with specified roles, and tags the group with labels that downstream IAM bindings reference. Removal cascades through Workspace, Calendar resource access, and Drive shared drives. Example prompt: Call POST /v1/groups with the group key and labels, then POST on the memberships sub-collection to add initial members ### SAML SSO Onboarding Security teams configure inbound SAML SSO so that authentication is delegated to an external IdP such as Okta or Entra ID. The flow creates an inboundSamlSsoProfile with the IdP metadata, then creates inboundSsoAssignments that scope the profile to specific org units or groups. Setup is one-off but precise and benefits from API automation across multiple tenancies. Example prompt: Call POST /v1/inboundSamlSsoProfiles with the IdP metadata, then POST /v1/inboundSsoAssignments to scope it to an org unit ### Device Compliance Enforcement Endpoint security teams use the devices endpoints to list enrolled devices, surface non-compliant ones, and trigger administrative actions such as wipe or block. The API supports both company-owned and BYOD enrollment models and integrates with Cloud Identity's device policies. Example prompt: Call GET /v1/devices with a filter on complianceState and trigger administrative actions on each non-compliant device ### AI Agent Directory Operator via Jentic An agent invoked by an IT helpdesk searches Jentic for the right Cloud Identity operation, creates groups or adds members based on a ticket, and reports back. Through Jentic, the agent never holds the underlying admin OAuth credential - Jentic injects a scoped token at execution time. Example prompt: Search Jentic for 'create google group', execute against POST /v1/groups with the requested groupKey, and add the requested members via the memberships sub-resource ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v1/groups | Create a new directory group | | GET | /v1/groups | List groups in the directory | | GET | /v1/groups:lookup | Look up a group by group key | | GET | /v1/groups:search | Search for groups by query | | GET | /v1/devices | List enrolled devices | | POST | /v1/inboundSamlSsoProfiles | Create an inbound SAML SSO profile | | POST | /v1/inboundSsoAssignments | Assign an SSO profile to an org unit or group | | GET | /v1/policies | List identity policies | ## Key resources - **Groups** — Directory groups with memberships, labels, and group keys - **Memberships** — Membership relationships between groups and users or other groups - **Devices** — Company-owned and BYOD devices enrolled into the tenancy - **InboundSamlSsoProfiles** — SAML SSO configurations for delegating authentication to an external IdP - **InboundSsoAssignments** — Assignments that scope SSO profiles to org units or groups - **Policies** — Identity policies applied at customer or org-unit scope ## Why Jentic - **Setup:** Wiring the Cloud Identity API by hand means setting up Google OAuth 2.0 admin credentials, minting short-lived tokens against the relevant cloud-identity scopes, and addressing groups and memberships by resource name against cloudidentity.googleapis.com yourself. Through Jentic you install once, import the Cloud Identity API from the API Directory, store the OAuth credential once, and your agent calls it. - **Permission scoping:** Cloud Identity puts the group and membership resource names in the URL path (/v1/{+name}, /v1/{+parent}/memberships), so a rule can pin your agent to one group: it can look up and modify membership roles there and nothing else. You choose the operations it may call, so device wipe or inbound SSO profile changes are not included unless you add them. - **Credential handling:** Your Cloud Identity OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a Google group' or 'configure SAML SSO', and Jentic returns the matching Cloud Identity operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Google Workspace Admin SDK** — Older directory and reporting API that overlaps with Cloud Identity for users and groups - **Identity and Access Management (IAM) API** — Grants Google Cloud roles to the users and groups that Cloud Identity provisions - **Cloud Channel API** — Provisions the Cloud Identity tenancy that this API then manages ## FAQ ### What authentication does the Cloud Identity API use? The Cloud Identity API uses OAuth 2.0 with cloud-identity scopes such as cloud-identity.groups and cloud-identity.devices. Tokens are issued for a Google admin user with delegated authority. Through Jentic, the OAuth credential lives in your Jentic One instance and the agent receives a short-lived access token only - the underlying credential never enters agent context. ### Can I create and manage Google Groups with this API? Yes. POST /v1/groups creates a new group with a groupKey (typically an email address) and labels that define the group type. Use the memberships sub-collection on the group resource to add or remove members. The lookup and search endpoints find existing groups by key or query. ### What are the rate limits for the Cloud Identity API? Cloud Identity API quotas are published per-method in the Google Cloud console under the Cloud Identity API quota page; typical defaults are several thousand read requests per minute per project, with lower limits on group and membership writes and stricter caps on device administrative actions. ### How do I configure SAML SSO through Jentic? Search Jentic for 'create cloud identity saml sso profile' and execute against POST /v1/inboundSamlSsoProfiles with the IdP metadata. Then call POST /v1/inboundSsoAssignments to scope the profile to the desired org units or groups. Cloud Identity then delegates authentication for those scopes to the configured IdP. ### Can I enroll and manage devices with this API? Yes. The devices collection supports listing, getting, and administrative actions like wipe and block on enrolled devices. Both company-owned and BYOD enrollment models are supported and behave as separate device categories with different policies. ### Is the Cloud Identity API free? The Cloud Identity API itself has no per-call charge. Cloud Identity Free and Cloud Identity Premium pricing is per-user per-month and is documented on the Cloud Identity pricing page; Workspace customers already include Cloud Identity in their subscription. ### Can I limit what my agent is allowed to do with the Cloud Identity API? Yes. Because you run your own self-hosted Jentic One instance, your rules decide which Cloud Identity operations and credentials the agent can use. Cloud Identity puts the group and membership resource names in the URL path (/v1/{+name} and /v1/{+parent}/memberships), so a rule can pin the agent to a single group where it may only look up and modify membership roles. You choose the operations it may call, so a device wipe or an inbound SAML SSO profile change is not included unless you add it.