Skip to content

People

octomate.schemas.user

Registered users and the channel profiles they own.

ANONYMOUS_CHANNEL_USER_ID module-attribute 

ANONYMOUS_CHANNEL_USER_ID = '0'

UserProfile

Bases: BaseTransmuter

An observed channel identity and the boundary channel-profile shape.

Persisted profiles belong to a registered User or remain ownerless visitors. Ephemeral channel snapshots also have no owner; UserManager stamps their channel id and resolves ownership from the registry row.

Source code in octomate/schemas/user.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
@sqlalchemy_materia.bless(UserProfileModel)
class UserProfile(BaseTransmuter):
    """An observed channel identity and the boundary channel-profile shape.

    Persisted profiles belong to a registered ``User`` or remain ownerless
    visitors. Ephemeral channel snapshots also have no owner; ``UserManager``
    stamps their channel id and resolves ownership from the registry row.
    """

    model_config = ConfigDict(
        validate_by_alias=True,
        validate_by_name=True,
        extra="ignore",
        coerce_numbers_to_str=True,
        from_attributes=True,
    )

    id: Annotated[UUID7, Identity] = Field(default_factory=uuid7, frozen=True)
    channel_tentacle_id: str = Field(
        default="",
        description=(
            "The channel this identity lives on; empty on ephemeral boundary "
            "instances, stamped by UserManager at persist time."
        ),
    )
    channel_user_id: str = ANONYMOUS_CHANNEL_USER_ID
    name: str = ""
    nickname: str | None = None
    gender: str | None = None
    age: int | None = None
    title: str | None = None

    user_id: UUID7 | None = Field(
        default=None,
        description=(
            "The registered owning User; None for ephemeral snapshots and "
            "persisted visitor profiles."
        ),
    )
    user: Relation[User | None] = Field(
        default_factory=Relation,
        frozen=True,
        exclude=True,
        description="The optional registered owner, eagerly loaded.",
    )

model_config class-attribute instance-attribute 

model_config = ConfigDict(
    validate_by_alias=True,
    validate_by_name=True,
    extra="ignore",
    coerce_numbers_to_str=True,
    from_attributes=True,
)

id class-attribute instance-attribute 

id: Annotated[UUID7, Identity] = Field(
    default_factory=uuid7, frozen=True
)

channel_tentacle_id class-attribute instance-attribute 

channel_tentacle_id: str = Field(
    default="",
    description="The channel this identity lives on; empty on ephemeral boundary instances, stamped by UserManager at persist time.",
)

channel_user_id class-attribute instance-attribute 

channel_user_id: str = ANONYMOUS_CHANNEL_USER_ID

name class-attribute instance-attribute 

name: str = ''

nickname class-attribute instance-attribute 

nickname: str | None = None

gender class-attribute instance-attribute 

gender: str | None = None

age class-attribute instance-attribute 

age: int | None = None

title class-attribute instance-attribute 

title: str | None = None

user_id class-attribute instance-attribute 

user_id: UUID7 | None = Field(
    default=None,
    description="The registered owning User; None for ephemeral snapshots and persisted visitor profiles.",
)

user class-attribute instance-attribute 

user: Relation[User | None] = Field(
    default_factory=Relation,
    frozen=True,
    exclude=True,
    description="The optional registered owner, eagerly loaded.",
)

User

Bases: BaseTransmuter

A registered human across channels.

Source code in octomate/schemas/user.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
@sqlalchemy_materia.bless(UserModel)
class User(BaseTransmuter):
    """A registered human across channels."""

    model_config = ConfigDict(
        from_attributes=True, json_schema_serialization_defaults_required=True
    )

    id: Annotated[UUID7, Identity] = Field(default_factory=uuid7, frozen=True)
    username: str = Field(
        frozen=True,
        description="Stable username naming this human across sign-in and channels.",
    )
    name: str = Field(
        default="",
        description="Canonical display name the agent uses for this human.",
    )
    nickname: str | None = Field(
        default=None,
        description="A shorter, casual name for this human.",
    )
    password_hash: SecretStr | None = Field(
        default=None,
        exclude=True,
        repr=False,
        description="Argon2id password hash; None until local sign-in is enrolled.",
    )
    profiles: RelationCollection[UserProfile] = Relationships(exclude=True)

model_config class-attribute instance-attribute 

model_config = ConfigDict(
    from_attributes=True,
    json_schema_serialization_defaults_required=True,
)

id class-attribute instance-attribute 

id: Annotated[UUID7, Identity] = Field(
    default_factory=uuid7, frozen=True
)

username class-attribute instance-attribute 

username: str = Field(
    frozen=True,
    description="Stable username naming this human across sign-in and channels.",
)

name class-attribute instance-attribute 

name: str = Field(
    default="",
    description="Canonical display name the agent uses for this human.",
)

nickname class-attribute instance-attribute 

nickname: str | None = Field(
    default=None,
    description="A shorter, casual name for this human.",
)

password_hash class-attribute instance-attribute 

password_hash: SecretStr | None = Field(
    default=None,
    exclude=True,
    repr=False,
    description="Argon2id password hash; None until local sign-in is enrolled.",
)

profiles class-attribute instance-attribute 

profiles: RelationCollection[UserProfile] = Relationships(
    exclude=True
)

ProfileInfo pydantic-model

Bases: BaseModel

An account with its channel profiles and MCP installations.

Fields:

Source code in octomate/schemas/user.py 
106
107
108
109
110
111
112
113
114
115
class ProfileInfo(BaseModel):
    """An account with its channel profiles and MCP installations."""

    user: User
    profiles: list[UserProfile] = Field(
        description="Every channel identity bound to this account."
    )
    mcps: list[McpServerSummary] = Field(
        description="This user's OAuth MCP installations and their authorization status."
    )

user pydantic-field 

user: User

profiles pydantic-field 

profiles: list[UserProfile]

Every channel identity bound to this account.

mcps pydantic-field 

mcps: list[McpServerSummary]

This user's OAuth MCP installations and their authorization status.

octomate.schemas.auth

Local account transmuters — invitations, sessions, profile-link tickets, API keys — and the token payloads sign-in returns.

UserInvitation

Bases: BaseTransmuter

A single-use registration invitation, stored by token hash.

Source code in octomate/schemas/auth.py 
28
29
30
31
32
33
34
35
36
37
38
@sqlalchemy_materia.bless(auth_models.UserInvitation)
class UserInvitation(BaseTransmuter):
    """A single-use registration invitation, stored by token hash."""

    model_config = ConfigDict(from_attributes=True)

    id: Annotated[UUID7, Identity] = Field(default_factory=uuid7, frozen=True)
    token_hash: SecretStr = Field(exclude=True, repr=False)
    expires_at: AwareDatetime
    consumed_at: AwareDatetime | None = None
    version: int = Field(default=1, exclude=True, repr=False)

model_config class-attribute instance-attribute 

model_config = ConfigDict(from_attributes=True)

id class-attribute instance-attribute 

id: Annotated[UUID7, Identity] = Field(
    default_factory=uuid7, frozen=True
)

token_hash class-attribute instance-attribute 

token_hash: SecretStr = Field(exclude=True, repr=False)

expires_at instance-attribute 

expires_at: AwareDatetime

consumed_at class-attribute instance-attribute 

consumed_at: AwareDatetime | None = None

version class-attribute instance-attribute 

version: int = Field(default=1, exclude=True, repr=False)

UserSession

Bases: BaseTransmuter

A signed-in session: hashed access and refresh tokens with their deadlines.

Source code in octomate/schemas/auth.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
@sqlalchemy_materia.bless(auth_models.UserSession)
class UserSession(BaseTransmuter):
    """A signed-in session: hashed access and refresh tokens with their
    deadlines."""

    model_config = ConfigDict(from_attributes=True)

    id: Annotated[UUID7, Identity] = Field(default_factory=uuid7, frozen=True)
    user_id: UUID7
    access_token_hash: SecretStr = Field(exclude=True, repr=False)
    refresh_token_hash: SecretStr = Field(exclude=True, repr=False)
    access_expires_at: AwareDatetime
    refresh_expires_at: AwareDatetime = Field(
        description="Absolute session deadline; refresh does not extend it."
    )
    created_at: AwareDatetime = Field(default_factory=lambda: datetime.now(UTC))
    revoked_at: AwareDatetime | None = None
    version: int = Field(default=1, exclude=True, repr=False)

model_config class-attribute instance-attribute 

model_config = ConfigDict(from_attributes=True)

id class-attribute instance-attribute 

id: Annotated[UUID7, Identity] = Field(
    default_factory=uuid7, frozen=True
)

user_id instance-attribute 

user_id: UUID7

access_token_hash class-attribute instance-attribute 

access_token_hash: SecretStr = Field(
    exclude=True, repr=False
)

refresh_token_hash class-attribute instance-attribute 

refresh_token_hash: SecretStr = Field(
    exclude=True, repr=False
)

access_expires_at instance-attribute 

access_expires_at: AwareDatetime

refresh_expires_at class-attribute instance-attribute 

refresh_expires_at: AwareDatetime = Field(
    description="Absolute session deadline; refresh does not extend it."
)

created_at class-attribute instance-attribute 

created_at: AwareDatetime = Field(
    default_factory=lambda: datetime.now(UTC)
)

revoked_at class-attribute instance-attribute 

revoked_at: AwareDatetime | None = None

version class-attribute instance-attribute 

version: int = Field(default=1, exclude=True, repr=False)

LinkProfileSession

Bases: BaseTransmuter

One channel profile's pending link ticket, stored by token hash.

Source code in octomate/schemas/auth.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
@sqlalchemy_materia.bless(auth_models.LinkProfileSession)
class LinkProfileSession(BaseTransmuter):
    """One channel profile's pending link ticket, stored by token hash."""

    model_config = ConfigDict(from_attributes=True)

    id: Annotated[UUID7, Identity] = Field(default_factory=uuid7, frozen=True)
    profile_id: UUID7 = Field(
        description="The exact channel profile this session may link."
    )
    token_hash: SecretStr = Field(exclude=True, repr=False)
    expires_at: AwareDatetime
    created_at: AwareDatetime = Field(default_factory=lambda: datetime.now(UTC))
    consumed_at: AwareDatetime | None = None
    version: int = Field(default=1, exclude=True, repr=False)

model_config class-attribute instance-attribute 

model_config = ConfigDict(from_attributes=True)

id class-attribute instance-attribute 

id: Annotated[UUID7, Identity] = Field(
    default_factory=uuid7, frozen=True
)

profile_id class-attribute instance-attribute 

profile_id: UUID7 = Field(
    description="The exact channel profile this session may link."
)

token_hash class-attribute instance-attribute 

token_hash: SecretStr = Field(exclude=True, repr=False)

expires_at instance-attribute 

expires_at: AwareDatetime

created_at class-attribute instance-attribute 

created_at: AwareDatetime = Field(
    default_factory=lambda: datetime.now(UTC)
)

consumed_at class-attribute instance-attribute 

consumed_at: AwareDatetime | None = None

version class-attribute instance-attribute 

version: int = Field(default=1, exclude=True, repr=False)

UserApiKey

Bases: BaseTransmuter

A personal API key: its hash, public prefix, scopes and lifetime.

Source code in octomate/schemas/auth.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@sqlalchemy_materia.bless(auth_models.UserApiKey)
class UserApiKey(BaseTransmuter):
    """A personal API key: its hash, public prefix, scopes and lifetime."""

    model_config = ConfigDict(from_attributes=True)

    id: Annotated[UUID7, Identity] = Field(default_factory=uuid7, frozen=True)
    user_id: UUID7
    name: str = Field(min_length=1, max_length=100)
    key_hash: SecretStr = Field(exclude=True, repr=False)
    key_prefix: str
    scopes: list[ApiKeyScope] = Field(min_length=1)
    created_at: AwareDatetime = Field(default_factory=lambda: datetime.now(UTC))
    expires_at: AwareDatetime | None = None
    revoked_at: AwareDatetime | None = None

model_config class-attribute instance-attribute 

model_config = ConfigDict(from_attributes=True)

id class-attribute instance-attribute 

id: Annotated[UUID7, Identity] = Field(
    default_factory=uuid7, frozen=True
)

user_id instance-attribute 

user_id: UUID7

name class-attribute instance-attribute 

name: str = Field(min_length=1, max_length=100)

key_hash class-attribute instance-attribute 

key_hash: SecretStr = Field(exclude=True, repr=False)

key_prefix instance-attribute 

key_prefix: str

scopes class-attribute instance-attribute 

scopes: list[ApiKeyScope] = Field(min_length=1)

created_at class-attribute instance-attribute 

created_at: AwareDatetime = Field(
    default_factory=lambda: datetime.now(UTC)
)

expires_at class-attribute instance-attribute 

expires_at: AwareDatetime | None = None

revoked_at class-attribute instance-attribute 

revoked_at: AwareDatetime | None = None

SessionTokens pydantic-model

Bases: BaseModel

Secrets returned only by successful login or refresh.

Fields:

Source code in octomate/schemas/auth.py 
 95
 96
 97
 98
 99
100
101
102
103
class SessionTokens(BaseModel):
    """Secrets returned only by successful login or refresh."""

    session_id: UUID7
    user_id: UUID7
    access_token: SecretStr = Field(repr=False)
    refresh_token: SecretStr = Field(repr=False)
    access_expires_at: AwareDatetime
    refresh_expires_at: AwareDatetime

session_id pydantic-field 

session_id: UUID7

user_id pydantic-field 

user_id: UUID7

access_token pydantic-field 

access_token: SecretStr

refresh_token pydantic-field 

refresh_token: SecretStr

access_expires_at pydantic-field 

access_expires_at: AwareDatetime

refresh_expires_at pydantic-field 

refresh_expires_at: AwareDatetime

LinkProfileInfo pydantic-model

Bases: BaseModel

The profile link an authenticated browser is being asked to confirm.

Fields:

Source code in octomate/schemas/auth.py 
106
107
108
109
110
class LinkProfileInfo(BaseModel):
    """The profile link an authenticated browser is being asked to confirm."""

    profile: UserProfile
    expires_at: AwareDatetime

profile pydantic-field 

profile: UserProfile

expires_at pydantic-field 

expires_at: AwareDatetime

LinkProfileAuthorization pydantic-model

Bases: LinkProfileInfo

The private host authorization request delivered through a channel or OAuth callback.

Fields:

Source code in octomate/schemas/auth.py 
114
115
116
117
class LinkProfileAuthorization(LinkProfileInfo):
    """The private host authorization request delivered through a channel or OAuth callback."""

    authorization_uri: AnyHttpUrl = Field(repr=False)

authorization_uri pydantic-field 

authorization_uri: AnyHttpUrl

IssuedApiKey pydantic-model

Bases: BaseModel

A freshly issued key with its one-time plaintext token.

Fields:

Source code in octomate/schemas/auth.py 
120
121
122
123
124
class IssuedApiKey(BaseModel):
    """A freshly issued key with its one-time plaintext token."""

    key: UserApiKey
    token: SecretStr = Field(repr=False)

key pydantic-field 

key: UserApiKey

token pydantic-field 

token: SecretStr