Skip to main content

​
User Invitations

The invitation system allows secure onboarding of new administrative users. Only users with the users:create permission can send invitations.

​
Creating an Invitation

To invite a new administrator, send a POST request to the /admin/invitations endpoint: 
POST /admin/invitations
{
  "role_id": 2,
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Smith"
}
The response will include the invitation details: 
{
  "success": true,
  "data": {
    "id": 1,
    "role": {
      "id": 2,
      "name": "Manager"
    },
    "inviter": {
      "id": 1,
      "name": "John Doe"
    },
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Smith",
    "full_name": "Jane Smith",
    "status": "pending",
    "expires_at": "2025-02-19T10:00:00Z",
    "created_at": "2025-02-12T10:00:00Z"
  }
}
An email will be sent to the invitee with a link to accept the invitation.

​
Invitation States

Invitations can be in one of three states:
  • pending - Awaiting acceptance
  • accepted - Successfully accepted and account created
  • expired - No longer valid (7 days after creation)

​
Accepting an Invitation

When the invitee clicks the invitation link, they’ll be taken to a page where they can set their password. The acceptance request should be sent to the /admin/invitations/accept endpoint: 
POST /admin/invitations/accept
{
  "token": "invitation-token-from-email",
  "password": "new-password",
  "password_confirmation": "new-password"
}
A successful response will include the new user account and access token: 
{
  "success": true,
  "data": {
    "user": {
      "id": 2,
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "[email protected]",
      "role": {
        "id": 2,
        "name": "Manager",
        "permissions": [...]
      }
    },
    "token": {
      "access_token": "1|abcdef123456...",
      "token_type": "Bearer",
      "expires_at": "2025-02-13T10:00:00Z"
    }
  }
}

​
Resending Invitations

If an invitation email needs to be resent, use the resend endpoint: 
POST /admin/invitations/{id}/resend
This will generate a new token and send a fresh invitation email. The previous token will be invalidated.

​
Canceling Invitations

To cancel a pending invitation: 
DELETE /admin/invitations/{id}
Only pending invitations can be canceled. Once an invitation has been accepted, it cannot be canceled.

​
Important Notes

  1. Invitations expire after 7 days
  2. Each email address can only have one pending invitation at a time
  3. Invitations cannot be created for email addresses that already have an account
  4. Only users with the users:create permission can manage invitations
  5. The invitation token is single-use and becomes invalid after acceptance
  6. Users are created with email verification automatically completed
  7. Role assignments cannot be changed during the acceptance process - a new invitation must be sent if a different role is needed