Invitation Endpoints

Accept and manage organization invitations

Overview

Invitation endpoints allow users to view, accept, or decline invitations to join organizations. These endpoints are user-centric, showing invitations received by the authenticated user.

All invitation endpoints require JWT authentication.

For organization-side invitation management (sending, canceling), see Organization Endpoints.

---

List User Invitations

GET · endpoint

/v1/invitations

List all pending invitations received by the authenticated user.

Response

invitations · array · required

List of pending invitations

Show Invitation Object

invitation_id · string · required

Invitation’s unique identifier

organization_id · string · required

Organization’s unique identifier

organization_name · string · required

Organization name

organization_slug · string

Organization’s URL-friendly slug

role · string · required

Role you’ll receive: owner, admin, or member

invited_by · string · required

User ID of the person who sent the invitation

invited_by_name · string

Name of the person who sent the invitation

invited_by_avatar · string

Avatar URL of the person who sent the invitation

sent_at · string · required

When the invitation was sent

expires_at · string · required

When the invitation expires

total · integer · required

Total number of pending invitations

Example

cURL

curl https://api.ryva.com/v1/invitations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "invitations": [
    {
      "invitation_id": "inv-123e4567-e89b-12d3-a456-426614174000",
      "organization_id": "org-987f6543-e21c-34d5-b678-537725285111",
      "organization_name": "Acme Corporation",
      "organization_slug": "acme-corporation",
      "role": "member",
      "invited_by": "user-abc123def",
      "invited_by_name": "John Doe",
      "invited_by_avatar": "https://example.com/avatar.jpg",
      "sent_at": "2026-03-03T10:30:00Z",
      "expires_at": "2026-03-10T10:30:00Z"
    },
    {
      "invitation_id": "inv-456xyz789",
      "organization_id": "org-abc789def",
      "organization_name": "Tech Startup Inc",
      "organization_slug": "tech-startup-inc",
      "role": "admin",
      "invited_by": "user-xyz789",
      "invited_by_name": "Jane Smith",
      "sent_at": "2026-03-02T14:00:00Z",
      "expires_at": "2026-03-09T14:00:00Z"
    }
  ],
  "total": 2
}

---

Accept Invitation

POST · endpoint

/v1/invitations/:id/accept

Accept an invitation to join an organization. The authenticated user must be invited to the organization at the provided email address.

Path Parameters

id · string · required

Invitation ID (UUID)

Response

organization_id · string · required

Organization’s unique identifier

organization_name · string · required

Organization name

role · string · required

Your role in the organization

message · string · required

Success message

Example

cURL

curl -X POST https://api.ryva.com/v1/invitations/inv-123e4567/accept \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "organization_id": "org-987f6543-e21c-34d5-b678-537725285111",
  "organization_name": "Acme Corporation",
  "role": "member",
  "message": "Successfully joined organization"
}

---

Decline Invitation

POST · endpoint

/v1/invitations/:id/decline

Decline an invitation to join an organization. This removes the invitation and notifies the organization.

Path Parameters

id · string · required

Invitation ID (UUID)

Response

Returns 204 No Content on success.

Example

cURL

curl -X POST https://api.ryva.com/v1/invitations/inv-123e4567/decline \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Invitation States

Invitations can be in one of the following states:

State	Description
Pending	Invitation has been sent and is awaiting response
Accepted	User has accepted and joined the organization
Declined	User has declined the invitation
Expired	Invitation has passed its expiration date
Canceled	Organization has canceled the invitation

Only pending invitations appear in the list endpoint. Accepted, declined, expired, or canceled invitations are automatically removed.

---

Invitation Expiration

Invitations expire after 7 days by default. After expiration:

• The invitation can no longer be accepted
• It’s automatically removed from the pending list
• Organization admins can resend the invitation if needed

Attempting to accept an expired invitation will return a 404 error.

---

Email Matching

When accepting an invitation:

1. The system checks that your authenticated email matches the invitation email
2. If emails don’t match, the request is rejected with a 403 error
3. This ensures invitations can only be accepted by the intended recipient

---

Error Responses

Invitation Not Found (404)

The invitation doesn’t exist, has expired, or has already been accepted/declined.

{
  "error": {
    "message": "Invitation not found or expired",
    "code": "NOT_FOUND",
    "status": 404
  }
}

Email Mismatch (403)

Your email doesn’t match the invitation email.

{
  "error": {
    "message": "This invitation was sent to a different email address",
    "code": "FORBIDDEN",
    "status": 403
  }
}

Already a Member (409)

You’re already a member of the organization.

{
  "error": {
    "message": "You are already a member of this organization",
    "code": "CONFLICT",
    "status": 409
  }
}

---

Next Steps

Organizations

Manage organizations and send invitations

Auth Endpoints

Manage your user profile