# UserInvitation object

div
strong
🔨 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](/docs/api-reference/objects/user-object) being invited. User record is created before invitation is sent.

**`organization_id`** string required

Reference to the [Organization](/docs/api-reference/objects/organization-object) the user is being invited to.

**`role_id`** string required

Reference to the [Role](/docs/api-reference/objects/role-object) 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)**


```json
{
  "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**


```json
{
  "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**


```json
{
  "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
}
```