> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/graphql-api/types/usertenants.md).

# UserTenants

UserTenants Type

Audience: Programmer

Represents a tenant (company/organization) that a user has access to, including their role within that tenant. This type enables multi-tenant user access in pyck, allowing users to belong to multiple organizations with different roles in each.

## Fields

| Field  | Type      | Description                                    |
| ------ | --------- | ---------------------------------------------- |
| `ID`   | `UUID!`   | Unique identifier of the tenant                |
| `Name` | `String!` | Human-readable name of the tenant/organization |
| `Role` | `String!` | User's role within this specific tenant        |

## Usage Example

```graphql
query {
  me {
    Username
    Email
    Tenants {
      ID
      Name
      Role
    }
  }
}
```

## Response Example

```json
{
  "data": {
    "me": {
      "Username": "john.doe",
      "Email": "john.doe@example.com",
      "Tenants": [
        {
          "ID": "123e4567-e89b-12d3-a456-426614174000",
          "Name": "Acme Corporation",
          "Role": "admin"
        },
        {
          "ID": "987f6543-a21b-34c5-d678-123456789012",
          "Name": "Beta Industries",
          "Role": "viewer"
        }
      ]
    }
  }
}
```

## Multi-Tenant Access

UserTenants enables sophisticated multi-tenant scenarios:

* **Multiple Organizations**: Users can belong to multiple companies/organizations
* **Role Isolation**: Each tenant association has its own role assignment
* **Tenant Switching**: Applications can allow users to switch between their accessible tenants
* **Permission Scoping**: Permissions are scoped to the specific tenant context

## Role Management

The `Role` field contains the user's role within the specific tenant:

* Roles are tenant-specific, not global
* A user can be an admin in one tenant and a viewer in another
* Role definitions are managed at the tenant level
* Role changes affect only the specific tenant association

## Common Use Cases

* **Consultants**: External users who need access to multiple client organizations
* **Shared Services**: Users who provide services across multiple business units
* **Parent-Child Companies**: Users who work across related but separate entities
* **Partner Access**: Granting limited access to business partners or suppliers
* **Administrative Oversight**: Super-users who manage multiple tenant instances

## Security Considerations

* Tenant isolation must be strictly enforced at the data layer
* Role validation should occur within the tenant context
* Audit logs should track which tenant context actions are performed in
* Session management should clearly indicate the active tenant

## Relationship with UserProfile

UserTenants is accessed through the `UserProfile.Tenants` field, replacing the deprecated `AssignedRoles` field:

```graphql
query {
  me {
    # Deprecated - use Tenants instead
    AssignedRoles
    
    # Recommended approach
    Tenants {
      ID
      Name
      Role
    }
  }
}
```

## Best Practices

* Always validate tenant access before performing operations
* Use tenant ID for data filtering and access control
* Display tenant name in the UI for clarity
* Implement tenant switching mechanisms in multi-tenant applications
* Log all cross-tenant operations for security auditing
* Cache tenant associations for performance while maintaining security


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pyck.cloud/graphql-api/types/usertenants.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.