> 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/userprofile.md).

# UserProfile

UserProfile Type

Audience: Programmer

Represents a comprehensive user profile containing authentication information, tenant associations, and role assignments. UserProfile provides a consolidated view of user data across the identity provider and internal system, supporting multi-tenant access patterns.

## Fields

| Field           | Type                | Description                                                              |
| --------------- | ------------------- | ------------------------------------------------------------------------ |
| `UserID`        | `UUID!`             | Internal user identifier                                                 |
| `Username`      | `String!`           | Username for authentication                                              |
| `Email`         | `String!`           | User's email address                                                     |
| `FirstName`     | `String!`           | User's first name                                                        |
| `LastName`      | `String!`           | User's last name                                                         |
| `TenantID`      | `UUID!`             | Primary tenant identifier                                                |
| `TenantName`    | `String!`           | Name of the primary tenant                                               |
| `AssignedRoles` | `[UserRoleTuple!]!` | **Deprecated** - List of role-tenant tuples. Use `Tenants` field instead |
| `Tenants`       | `[UserTenants!]!`   | List of accessible tenants with role assignments                         |

## Usage Example

```graphql
query {
  me {
    UserID
    Username
    Email
    FirstName
    LastName
    TenantID
    TenantName
    # Use Tenants for multi-tenant access
    Tenants {
      ID
      Name
      Role
    }
  }
}
```

## Authentication Context

UserProfile is typically used to retrieve the current authenticated user's information:

```graphql
query {
  me {
    Username
    Email
    FirstName
    LastName
    TenantName
    # Recommended: Use Tenants for role information
    Tenants {
      ID
      Name
      Role
    }
  }
}
```

## Role-Based Access

The `Tenants` field provides tenant-specific role assignments, replacing the deprecated `AssignedRoles` field:

* **Multi-Tenant Support**: Users can have different roles in different tenants
* **Authorization Decisions**: Role-based access control within tenant context
* **UI Customization**: Adapt interface based on tenant-specific permissions
* **Feature Availability**: Enable/disable features based on role and tenant
* **Audit Logging**: Track actions with full tenant and role context

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

### Migration from AssignedRoles

The `AssignedRoles` field is deprecated. Applications should migrate to using the `Tenants` field:

```graphql
# Old approach (deprecated)
query {
  me {
    AssignedRoles {
      Role
      TenantID
    }
  }
}

# New approach (recommended)
query {
  me {
    Tenants {
      ID
      Name
      Role
    }
  }
}
```

## Tenant Association

UserProfile establishes the connection between users and their tenants (companies/organizations):

* **TenantID**: Primary tenant identifier for the user
* **TenantName**: Human-readable name of the primary tenant
* **Tenants**: Complete list of accessible tenants with role assignments

### Primary vs. Multiple Tenants

* The `TenantID` and `TenantName` fields represent the user's primary tenant
* The `Tenants` array contains all tenants the user has access to
* Users can switch between tenants while maintaining appropriate role-based access

## Identity Provider Integration

UserProfile bridges internal user management with external identity providers:

* **UserID**: Internal pyck user identifier
* External identity provider integration is handled transparently
* Tenant associations are synchronized with the identity provider

## Common Use Cases

* **User Authentication**: Verifying user identity and retrieving basic profile information
* **Authorization**: Checking user roles and permissions for access control
* **User Interface Personalization**: Customizing the UI based on user preferences and roles
* **Audit Logging**: Recording user actions with complete profile context
* **Multi-Tenant Operations**: Managing access across multiple tenants with appropriate role-based permissions
* **Role Management**: Displaying and managing user role assignments

## Security Considerations

* UserProfile contains sensitive information and should only be accessible to authenticated users
* Role information should be used for authorization decisions throughout the application
* Tenant isolation must be enforced based on the active tenant context from the Tenants list
* Identity provider integration requires secure token validation

## Integration with Identity Providers

UserProfile is designed to work with external identity providers like Zitadel:

* Synchronizes user information from the identity provider
* Maintains mapping between internal and external user identifiers
* Supports single sign-on (SSO) workflows
* Handles role synchronization from external systems

## Best Practices

* Always validate user authentication before returning profile information
* Use role information consistently across the application for access control
* Implement proper tenant isolation using the selected tenant from the Tenants list
* Keep user profile information synchronized with the identity provider
* Log user profile access for security auditing
* Consider caching profile information 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/userprofile.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.