The invitation system allows account owners to invite users to join their accounts. Invitations are sent via email and include encrypted account keys for secure data sharing.
Create Invitation Create a new invitation to add a member to the account. Only the account owner can create invitations.
Authentication Requires authentication token and CSRF token.
Path Parameters Request Body Email address of the user to invite
Encrypted account key to share with the invited user. This allows the invited user to decrypt account data.
Response The created invitation object Show invitation properties
Unique invitation identifier (UUID)
Account ID this invitation is for
User ID of the account owner who created the invitation
Email address of the invited user
Unique 64-character hex token for the invitation
Invitation status: pending, accepted, expired, or revoked
ISO 8601 timestamp when the invitation expires (24 hours from creation)
ISO 8601 timestamp of when the invitation was created
Relative path to the invitation page (e.g., /invite/{token})
Example Request curl -X POST https://api.example.com/api/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/invitations \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \ -d '{ "email": "[email protected]", "encryptedKey": "encrypted_account_key_here" }'
Example Response { "invitation" : { "id" : "inv-uuid-here" , "account_id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "invited_by" : "owner-user-id" , "email" : "[email protected]" , "token" : "64-character-hex-token-here" , "status" : "pending" , "expires_at" : "2026-03-06T10:30:00.000Z" , "created_at" : "2026-03-05T10:30:00.000Z" }, "inviteLink" : "/invite/64-character-hex-token-here" }
Error Responses 400 Bad Request { "error" : "Email es requerido" }
{ "error" : "Este usuario ya es miembro de la cuenta" }
403 Forbidden { "error" : "Solo el propietario puede invitar miembros" }
List Invitations Get all invitations for an account. Both owners and members can view invitations.
Authentication Requires authentication token.
Path Parameters Response Array of invitation objects, ordered by creation date (newest first)
Example Request curl -X GET https://api.example.com/api/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/invitations \ -H "Authorization: Bearer YOUR_TOKEN"
Example Response { "invitations" : [ { "id" : "inv-uuid-1" , "account_id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "invited_by" : "owner-user-id" , "email" : "[email protected]" , "token" : "token-1" , "status" : "pending" , "invited_user_id" : null , "expires_at" : "2026-03-06T10:30:00.000Z" , "created_at" : "2026-03-05T10:30:00.000Z" , "accepted_at" : null }, { "id" : "inv-uuid-2" , "account_id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "invited_by" : "owner-user-id" , "email" : "[email protected]" , "token" : "token-2" , "status" : "accepted" , "invited_user_id" : "user-uuid" , "expires_at" : "2026-03-05T09:00:00.000Z" , "created_at" : "2026-03-04T09:00:00.000Z" , "accepted_at" : "2026-03-04T11:30:00.000Z" } ] }
Get Invitation by Token View invitation details using the invitation token. This endpoint is public and does not require authentication.
Path Parameters The invitation token (64-character hex string)
Response Invitation details with account information Show invitation properties
Current status: pending, accepted, expired, or revoked
Name of the account the user is being invited to
Name of the user who sent the invitation
ISO 8601 timestamp when the invitation expires
Encrypted account key for secure data sharing (if provided)
Whether the invitation has expired
Example Request curl -X GET https://api.example.com/api/invitations/64-character-hex-token-here
Example Response { "invitation" : { "status" : "pending" , "account_id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "account_name" : "Personal Finances" , "invited_by_name" : "John Doe" , "expires_at" : "2026-03-06T10:30:00.000Z" , "encrypted_key" : "encrypted_key_here" }, "isExpired" : false }
Error Responses 404 Not Found { "error" : "Invitación no encontrada" }
Accept Invitation Accept an invitation and join the account. The authenticated user must have an email matching the invitation.
Authentication Requires authentication token.
Path Parameters Response Updated invitation object with accepted status
Basic account information Example Request curl -X POST https://api.example.com/api/invitations/64-character-hex-token-here/accept \ -H "Authorization: Bearer YOUR_TOKEN"
Example Response { "message" : "Invitación aceptada" , "invitation" : { "id" : "inv-uuid" , "account_id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "status" : "accepted" , "invited_user_id" : "user-uuid" , "accepted_at" : "2026-03-05T10:35:00.000Z" }, "account" : { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "name" : "" } }
Error Responses 400 Bad Request { "error" : "La invitación ha expirado" }
{ "error" : "La invitación ya fue aceptada" }
{ "error" : "Esta invitación es para otro email" }
{ "error" : "Ya eres miembro de esta cuenta" }
Update Invitation Key Update the encrypted key for an existing pending invitation. Only the account owner can update invitation keys.
Authentication Requires authentication token and CSRF token.
Path Parameters Request Body The new encrypted account key
Response Indicates if the operation was successful
Example Request curl -X PATCH https://api.example.com/api/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/invitations/inv-uuid/key \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \ -d '{ "encryptedKey": "new_encrypted_key_here" }'
Example Response Error Responses 400 Bad Request { "error" : "encryptedKey es requerido" }
403 Forbidden { "error" : "Solo el propietario puede actualizar invitaciones" }
Revoke Invitation Revoke a pending invitation. Only the account owner can revoke invitations.
Authentication Requires authentication token and CSRF token.
Path Parameters Response Example Request curl -X DELETE https://api.example.com/api/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/invitations/inv-uuid \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "X-CSRF-Token: YOUR_CSRF_TOKEN"
Example Response { "message" : "Invitación revocada" }
Error Responses 403 Forbidden { "error" : "Solo el propietario puede revocar invitaciones" }
404 Not Found { "error" : "Invitación no encontrada o ya procesada" }
Invitation Flow The invitation system follows this workflow:
Owner creates invitation : The account owner creates an invitation with the invitee’s email address and optionally includes an encrypted account key.
Token generation : A unique 64-character hex token is generated, valid for 24 hours.
Invitation sent : The invitee receives the invitation link (/invite/{token}).
Public verification : Anyone with the token can view basic invitation details (no auth required).
User accepts : The invited user (authenticated) accepts the invitation. The system verifies:
The token is valid and not expired
The user’s email matches the invitation email
The user is not already a member
Member added : Upon acceptance, the user is added to the account with the member role.
Key Sharing The encryptedKey field enables secure sharing of account encryption keys:
The owner encrypts the account key before creating the invitation
The encrypted key is stored with the invitation
When the invitee accepts, they can decrypt the key and access encrypted account data
Keys can be updated on pending invitations using the PATCH endpoint
Invitation States
pending : Invitation created and waiting for acceptanceaccepted : User has joined the accountexpired : Invitation passed the 24-hour expiration timerevoked : Owner cancelled the invitation before acceptance
Notes
Invitations expire after 24 hours
If a pending invitation exists for an email, creating a new one refreshes the token and expiration
Only pending invitations can be revoked
Users cannot accept invitations for accounts they’re already members of
The invitation email must match the accepting user’s email
