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

## Benefits of the IAM API

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Credential Introspection">
    See what the authenticated connection itself can do: `GET /unified/iam/me` returns its auth type, granted scopes, and effective permissions.
  </Accordion>
</AccordionGroup>

## StackOne SDKs & OpenAPI Specification

<p class="sdk-text">Use our official SDKs for faster integration. Build with language-native libraries. Full list [here](/platform-api/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>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.