Table of Contents

Class ProjectInvitationsController

Namespace
Builvero.Api.Controllers
Assembly
Builvero.Api.dll

Provides API endpoints for managing project invitations, including creating invitations, retrieving incoming/outgoing invitations, responding to invitations, and canceling invitations.

[ApiController]
[Route("api/invitations")]
[Authorize]
public class ProjectInvitationsController : ControllerBase
Inheritance
ProjectInvitationsController
Inherited Members

Remarks

All endpoints require authentication (JWT token) except for token-based response endpoints which are public. This controller handles:

  • Creating invitations to join projects (project owners/team members only)
  • Retrieving incoming invitations (invitations sent to the authenticated user)
  • Retrieving outgoing invitations (invitations sent by the authenticated user)
  • Responding to invitations (accept or decline)
  • Responding to invitations via secure token (public endpoint, no authentication required)
  • Canceling pending invitations (inviter only)

Invitations include a secure token that allows recipients to accept/decline via email links without requiring login. Invitations expire after 30 days if not responded to.

Constructors

ProjectInvitationsController(IProjectInvitationService)

Initializes a new instance of the ProjectInvitationsController class.

public ProjectInvitationsController(IProjectInvitationService invitationService)

Parameters

invitationService IProjectInvitationService

Service for project invitation operations.

Methods

CancelInvitation(Guid, CancellationToken)

Cancels a pending project invitation.

[HttpPost("{invitationId}/cancel")]
public Task<ActionResult<ProjectInvitationDto>> CancelInvitation(Guid invitationId, CancellationToken cancellationToken)

Parameters

invitationId Guid

The unique identifier of the invitation to cancel.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ProjectInvitationDto>>

200 OK: Returns updated ProjectInvitationDto with status set to Cancelled

403 Forbidden: User attempts to cancel an invitation they didn't create

400 Bad Request: Invitation not found, already responded to, or other error

Remarks

Requires authentication. Only the user who created the invitation (the inviter) can cancel it. Only pending invitations can be canceled. Once canceled, the invitation cannot be accepted or declined.

CreateInvitation(Guid, CreateProjectInvitationRequest, CancellationToken)

Creates a new project invitation, inviting a user to join a project.

[HttpPost("projects/{projectId}")]
public Task<ActionResult<ProjectInvitationDto>> CreateInvitation(Guid projectId, CreateProjectInvitationRequest request, CancellationToken cancellationToken)

Parameters

projectId Guid

The unique identifier of the project to invite the user to.

request CreateProjectInvitationRequest

The invitation request containing the target user ID and optional message.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ProjectInvitationDto>>

200 OK: Returns created ProjectInvitationDto

403 Forbidden: User does not have permission to invite users to this project

400 Bad Request: Invalid request data, project not found, user already a member, or other error

Remarks

Requires authentication. Only project owners and team members can create invitations. The invitation includes a secure token and expires after 30 days. An email notification is sent to the invitee.

GetIncomingInvitations(CancellationToken)

Retrieves all incoming project invitations for the authenticated user (invitations sent to them).

[HttpGet("incoming")]
public Task<ActionResult<List<ProjectInvitationDto>>> GetIncomingInvitations(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<List<ProjectInvitationDto>>>

200 OK: Returns list of ProjectInvitationDto objects

400 Bad Request: Error retrieving invitations

Remarks

Requires authentication. Returns all invitations where the authenticated user is the invitee, regardless of status (Pending, Accepted, Declined, Cancelled, Expired).

GetOutgoingInvitations(CancellationToken)

Retrieves all outgoing project invitations sent by the authenticated user.

[HttpGet("outgoing")]
public Task<ActionResult<List<ProjectInvitationDto>>> GetOutgoingInvitations(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<List<ProjectInvitationDto>>>

200 OK: Returns list of ProjectInvitationDto objects

400 Bad Request: Error retrieving invitations

Remarks

Requires authentication. Returns all invitations where the authenticated user is the inviter, regardless of status. Useful for project owners to track invitations they've sent.

RespondToInvitation(Guid, RespondToInvitationRequest, CancellationToken)

Responds to a project invitation by accepting or declining it.

[HttpPost("{invitationId}/respond")]
public Task<ActionResult<ProjectInvitationDto>> RespondToInvitation(Guid invitationId, RespondToInvitationRequest request, CancellationToken cancellationToken)

Parameters

invitationId Guid

The unique identifier of the invitation to respond to.

request RespondToInvitationRequest

The response request containing accept/decline decision and optional reason.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ProjectInvitationDto>>

200 OK: Returns updated ProjectInvitationDto

403 Forbidden: User attempts to respond to an invitation that doesn't belong to them

400 Bad Request: Invitation not found, already responded to, expired, or other error

Remarks

Requires authentication. Only the invitee can respond to an invitation. If accepted, creates an active project membership. If declined, marks the invitation as declined. An email notification is sent to the inviter.

RespondToInvitationByToken(RespondToInvitationByTokenRequest, CancellationToken)

Responds to a project invitation using a secure token (public endpoint, no authentication required).

[HttpPost("respond-by-token")]
[AllowAnonymous]
public Task<ActionResult<ProjectInvitationDto>> RespondToInvitationByToken(RespondToInvitationByTokenRequest request, CancellationToken cancellationToken)

Parameters

request RespondToInvitationByTokenRequest

The response request containing the invitation token, accept/decline decision, and optional reason.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ProjectInvitationDto>>

200 OK: Returns updated ProjectInvitationDto

400 Bad Request: Invalid token, invitation not found, already responded to, expired, or other error

Remarks

This is a public endpoint (no authentication required) that allows users to respond to invitations via email links. The secure token is included in the invitation email and provides access without requiring login. If accepted, creates an active project membership. If declined, marks the invitation as declined.

Edit this page