Unified IAM API

Unified IAM API for identity and access management across providers, with consistent data models for users, roles, groups, organizations, permissions, and credentials.

Benefits of the IAM API

Consistent Identity Data Models

Users, roles, groups, organizations, permissions, and credentials return the same schema regardless of the underlying provider. users in Google Workspace, Okta, and 1Password all return the same fields.

Fine-Grained Permissions and Scopes

Permissions carry an action type and resource scopes, and roles can be scoped to a specific organizational context, giving you a normalized view of who can do what, and where.

Resource-Level Access Visibility

List every user with access to a specific resource — a Drive file, a Slack channel, a group — including their resource-scoped roles.

Nested Groups and Organizations

Groups nest via parent and child links, belong to organizations, and expand to their member users, giving you the provider’s directory structure in one shape.

Credential Introspection

See what the authenticated connection itself can do: GET /unified/iam/me returns its auth type, granted scopes, and effective permissions.

StackOne SDKs & OpenAPI Specification

Use our official SDKs for faster integration. Build with language-native libraries. Full list here.

OpenAPI Specification

Click here

Popular SDKs

Node.js Java (JVM) PHP Ruby

Entity Model

The IAM API is built around six core entities.

IamCredentials is not included in the diagram above. It is a snapshot of the current connection’s auth state, not a stored identity object. It carries a user reference when the credential corresponds to a known principal (such as an OAuth user or named service account).

Entity	Description
IamUser	An individual with access to the provider. Carries profile fields, activity timestamps, MFA status, and expandable collections of roles, groups, and direct permissions.
IamRole	A named set of permissions. Roles can be scoped to a specific resource type and ID (scope), making them applicable to a particular group, organization, or resource.
IamGroup	A collection of users. Groups can nest via parent_id and child_group_ids, belong to an organization, and carry their own role assignments. Expand users to get group members.
IamOrganization	A top-level tenant or workspace. Groups and users are linked to an organization via organization_id and filter parameters.
IamPermission	A specific action type scoped to one or more resource types and optional resource IDs. Targets live on scopes (IamPermissionScope[]). See Permission types for valid type values.
IamCredentials	The authenticated connection making the request. Returned by GET /unified/iam/me. Includes a name, auth type, granted scopes, effective permissions, last-used timestamp, and a user reference when the credential corresponds to a known principal.

Permission and scope model

IamPermission has a type (the action) and a scopes array. Each scope entry has a resource_type (e.g. file, channel, user) and an optional resource_id. When resource_id is absent, the permission applies to all resources of that type.

Roles carry the same scoping via IamRoleScope on the role itself, allowing a role to be valid only within a specific organizational context.

Endpoints

Method	Path	Action	Description
GET	/unified/iam/users	unified_list_users	List users (see User filters)
GET	/unified/iam/users/{id}	unified_get_user	Get user by ID
PATCH	/unified/iam/users/{id}	iam_update_user	Update user
DELETE	/unified/iam/users/{id}	iam_delete_user	Delete user
GET	/unified/iam/roles	unified_list_roles	List roles
GET	/unified/iam/roles/{id}	unified_get_role	Get role by ID
GET	/unified/iam/groups	unified_list_groups	List groups
GET	/unified/iam/groups/{id}	unified_get_group	Get group by ID
GET	/unified/iam/organizations	unified_list_organizations	List organizations
GET	/unified/iam/organizations/{id}	unified_get_organization	Get organization by ID
GET	/unified/iam/me	unified_get_me	Get current connection credentials
GET	/unified/iam/resource_types	unified_list_resource_types	List resource type identifiers supported by this connector (see Resource types)
GET	/unified/iam/resource_users	unified_list_resource_users	List users with access to a specific resource. Requires resource_type and resource_id (see Listing users by resource)

Permission types

IamPermission.type is one of the values below. The OAS admits the full set; providers expose only the permission types that map to their model.

Value	Description
read	Read access
read_write	Read and write access
write	Write access
comment	Comment / annotate
create	Create new resources
edit	Edit existing resources
approve	Approval / workflow rights
delete	Delete access
use	Use / execute (e.g. run app, use license)
export	Export / download
unmapped_value	Provider value did not map to the enum
null	Provider did not provide a value

User filters

GET /unified/iam/users accepts the following keys on the filter query object. Filter support varies per connector; passing a filter key the connector does not support returns a 400.

Filter	Type	Notes
filter.updated_after	string (date-time)	Supported by all connectors
filter.email	string	Some connectors
filter.group_id	string	Some connectors
filter.role_id	string	Some connectors
filter.organization_id	string	Some connectors

Resource types

GET /unified/iam/resource_types returns the resource type identifiers a connected provider supports for resource-scoped queries. The response shape is { data: string[] }; values are connector-defined, not a fixed enum.

Connector	Example response
Google Drive	["file", "folder", "drive"]
Google Directory	["group"]
Slack	["channel", "workspace"]

Use these values as the resource_type query parameter on GET /unified/iam/resource_users.

The type field on an embedded IamResource is declared as oneOf: [string, IamResourceTypeEnum] in the OAS. Current connectors emit a plain string from the connector-defined set returned by this endpoint (e.g. "file", "channel", "group"). Legacy V2 connectors emit the { value, source_value } envelope where value is from the fixed IamResourceTypeEnum set. Parse both shapes when consuming the field.

Listing users by resource

GET /unified/iam/resource_users returns users with access to a specific resource, including their resource-scoped roles. Same response shape as IamUser.

Required query parameters:

• resource_type: one of the values returned by GET /unified/iam/resource_types for the connected provider.
• resource_id: the raw provider remote_id of the resource. Not a StackOne-encoded id from a list endpoint. Pass the provider’s native id (e.g. a Drive file id, Slack channel id, group remote_id).

Standard pagination, fields, and expand apply as on the other list endpoints.