Skip to content
/
UserInvitation
Last updated

UserInvitation object

🔨 In Development — This section is still being developed and may change.
The UserInvitation object tracks invitation links sent to users to join an organization. It manages invitation lifecycle including expiration and usage tracking.

Properties

Identity

id string required

Unique invitation identifier. Format: uinv_ followed by 12 alphanumeric characters.

email_key string required

Unique invitation key sent in email. Format: inv_ followed by 32 hexadecimal characters. This is the token users use to accept invitations.

Relationships

user_id string required

Reference to the User being invited. User record is created before invitation is sent.

organization_id string required

Reference to the Organization the user is being invited to.

role_id string required

Reference to the Role that will be assigned when the invitation is accepted.

Invitation Details

email string required

Email address where the invitation was sent.

Expiration

created_at string required

Timestamp when the invitation was created. Format: ISO 8601 datetime string.

expires_at string required

Timestamp when the invitation expires. Format: ISO 8601 datetime string. Default: 7 days from creation.

Usage Tracking

is_used boolean required

Whether the invitation has been used (accepted). Default: false.

used_at string | null optional

Timestamp when the invitation was accepted. Format: ISO 8601 datetime string. null if not yet used.

Invitation Lifecycle

  1. Created: Admin invites user, invitation record created with unique email_key
  2. Sent: Email sent to user with invitation link containing email_key
  3. Pending: User has 7 days to accept invitation
  4. Accepted: User clicks link and completes registration, is_used set to true
  5. Expired: If not accepted within 7 days, invitation becomes invalid

Security

  • Each invitation has a unique cryptographically secure email_key
  • Invitations automatically expire after 7 days
  • Used invitations cannot be reused
  • Email address is validated before sending

Active Invitation (Pending)

{
  "id": "uinv_a1b2c3d4e5f6",
  "email_key": "inv_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
  "user_id": "uid_newuser123456789",
  "organization_id": "ORG_A1B2C3D4E5F6G7H8",
  "role_id": "rol_member_xyz789",
  "email": "newuser@company.com",
  "created_at": "2025-01-15T10:00:00Z",
  "expires_at": "2025-01-22T10:00:00Z",
  "is_used": false,
  "used_at": null
}

Accepted Invitation

{
  "id": "uinv_b2c3d4e5f6g7",
  "email_key": "inv_2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q",
  "user_id": "uid_john_doe_987654",
  "organization_id": "ORG_A1B2C3D4E5F6G7H8",
  "role_id": "rol_admin_abc123",
  "email": "john.doe@company.com",
  "created_at": "2025-01-10T09:00:00Z",
  "expires_at": "2025-01-17T09:00:00Z",
  "is_used": true,
  "used_at": "2025-01-10T14:30:00Z"
}

Expired Invitation

{
  "id": "uinv_c3d4e5f6g7h8",
  "email_key": "inv_3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r",
  "user_id": "uid_expired_user_111",
  "organization_id": "ORG_A1B2C3D4E5F6G7H8",
  "role_id": "rol_member_xyz789",
  "email": "expired@company.com",
  "created_at": "2025-01-01T09:00:00Z",
  "expires_at": "2025-01-08T09:00:00Z",
  "is_used": false,
  "used_at": null
}
Previous page
Next page