> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

## 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

<Tip>
  **Building AI agents?** Use the [MCP Server](/mcp/quickstart), an [AI Toolset SDK](/agents/typescript/introduction), or the [Actions API (RPC)](/platform/api-reference/actions/make-an-rpc-call-to-an-action) instead — same data, optimized for LLM tool calling.
</Tip>

## Entity Model

The IAM API is built around six core entities.

```mermaid theme={null}
erDiagram
    IamUser ||--o{ IamRole : "has roles"
    IamUser ||--o{ IamGroup : "member of"
    IamUser ||--o{ IamPermission : "direct permissions"

    IamGroup ||--o{ IamRole : "has roles"
    IamGroup ||--o{ IamUser : "users (expandable)"
    IamGroup }o--o| IamGroup : "parent"
    IamGroup }o--o| IamOrganization : "belongs to"

    IamRole ||--o{ IamPermission : "grants"
    IamRole }o--o| IamRoleScope : "scope"

    IamPermission ||--o{ IamPermissionScope : "scopes"

    IamOrganization ||--o{ IamUser : "users"
    IamOrganization ||--o{ IamGroup : "groups"

    IamUser {
        string id
        string remote_id
        string primary_email_address
        string first_name
        string last_name
        string name
        string username
        boolean is_bot_user
        enum status
        array roles
        array groups
        array permissions
        datetime last_active_at
        datetime last_login_at
        datetime created_at
        datetime updated_at
        array multi_factor_enabled
        object avatar
    }

    IamRole {
        string id
        string remote_id
        string name
        string description
        enum type
        array permissions
        object scope
        datetime created_at
        datetime updated_at
    }

    IamGroup {
        string id
        string remote_id
        string name
        string description
        enum type
        array roles
        string parent_id
        string remote_parent_id
        array child_group_ids
        string organization_id
        array users
        datetime created_at
        datetime updated_at
    }

    IamOrganization {
        string id
        string remote_id
        string name
        datetime created_at
        datetime updated_at
    }

    IamPermission {
        string id
        string remote_id
        string name
        string description
        enum type
        array scopes
        datetime created_at
        datetime updated_at
    }

    IamPermissionScope {
        string resource_type
        string resource_id
    }

    IamRoleScope {
        string resource_type
        string resource_id
    }
```

<Note>
  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).
</Note>

| 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](#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](#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](#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](#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. 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

<p class="sdk-text">Use our official SDKs for faster integration. Build with language-native libraries. Full list [here](/guides/stackone-api-sdks).</p>

<CardGroup cols={2}>
  <Card title="OpenAPI Specification" icon="link" href="https://api.eu1.stackone.com/oas/iam.json" arrow="true" cta="Click here" />

  <Card title="Popular SDKs" icon="download" class="sdk-card">
    [Node.js](https://www.npmjs.com/package/@stackone/stackone-client-ts)
    [Java (JVM)](https://mvnrepository.com/artifact/com.stackone/stackone-client-java)
    [PHP](https://packagist.org/packages/stackone/client-sdk)
    [Ruby](https://rubygems.org/gems/stackone_client)
  </Card>
</CardGroup>