What is a Unified API?
A unified API provides a single, standardized interface to interact with multiple third-party providers. Instead of learning each provider’s unique API format, authentication scheme, and data model, you write code once, and StackOne handles the differences.
What StackOne normalizes:
- Data models – Consistent field names and structures across providers (e.g.,
files in Google Drive, SharePoint, and Dropbox all return the same schema; users in Google Workspace, Okta, and 1Password all return the same schema)
- Authentication – OAuth, API keys, and tokens are managed per-provider; you just pass an
x-account-id header
- Pagination – Cursor-based pagination works the same regardless of whether the provider uses offsets, pages, or cursors
- Error formats – Standardized error responses with provider-specific details when available
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"] |
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. Falcon 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.
StackOne SDKs & OpenAPI Specification
Use our official SDKs for faster integration. Build with language-native libraries. Full list here.
MCP
A2A