Audience: Application developers
Editorial status: Published — Source Validated
Product: FeraCalendar
Classification: administrative
POST /api/v1/calendars/share
Overview
Implements controller.share in routes/api/v1/calendar/routes.js:9. The authenticated boundary enforces managed-product and owner/member role rules, uses owner-scoped keys/UUIDs, applies visibility masks only after access resolution, and records mutations.
Deprecated compatibility paths
POST /api/calendars/share
Use the versioned canonical path for new integrations.
Authentication and access
Security scheme: authToken
| Control | Contract |
|---|---|
| Authentication | authenticated |
| Authorization | The route validates a JWT but does not invoke the available FeraAuth named-permission checker; VIEW/EDIT calendar, person, resource, and event grants are provisioned for owners but are not enforced by this router. The service additionally requires the inviter to own the calendar or hold owner, admin, or editor membership. |
| Licensing | The global managed-product middleware requires the resolved FeraCal product instance to exist in Active lifecycle state before this route executes. |
| Instance Context | The instance header selects the FeraCal product instance. A trusted API-plane caller may replace it only with signed x-feradel-owner-instance, service, timestamp, and scope-signature headers. |
| Ownership | The command’s owner field defaults to the resolved product instance but, in the current implementation, a caller-supplied owner UUID is used without an equality check against that instance. This is a documented runtime isolation constraint; role checks described for sharing/events still apply. |
Parameters
No operation parameters.
Request body
Source-traced FeraCal JSON command.
application/json
Schema: CalMutation
{
"owner": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"name": "Client meetings",
"timeZone": "America/New_York",
"visibility": 7,
"person": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"role": "editor"
}Example request
cURL
curl --request POST \ \
--url 'https://cal.feradel.com/api/v1/calendars/share' \
--header 'x-auth-token: $FERA_AUTH_TOKEN' \
--header 'content-type: application/json' \
--data '{"owner":"715c9ebb-0470-11f1-a928-0ed2cd1b87df","name":"Client meetings","timeZone":"America/New_York","visibility":7,"person":"715c9ebb-0470-11f1-a928-0ed2cd1b87df","role":"editor"}'Responses
200 The source-traced FeraCal handler completed and returned its calendar, event, person, resource, access, invitation, or lifecycle representation.
Content type: application/json; schema: CalResult
{
"success": true,
"item": {
"uuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"name": "Client consultation",
"calendarUuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"startsAt": "2026-09-01T13:00:00Z",
"endsAt": "2026-09-01T14:00:00Z",
"attendees": [],
"resources": []
},
"items": [],
"uuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"visibility": 7
}400 UUID, key, date range, fields, invite target, or command validation failed.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}401 The x-auth-token or lifecycle HMAC is invalid.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}403 Managed-product, owner, role, share/inviter, or lifecycle sender permission is missing.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}404 The owner-scoped calendar, event, person, resource, or invite target was not found.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}500 Persistence, invitation, lifecycle, or internal calendar processing failed.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}Status and retry matrix
| Status | Condition | Retryable | Developer action |
|---|---|---|---|
200 |
The source-traced FeraCal handler completed and returned its calendar, event, person, resource, access, invitation, or lifecycle representation. | No | Continue with the returned calendar state. |
400 |
UUID, key, date range, fields, invite target, or command validation failed. | No | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
401 |
The x-auth-token or lifecycle HMAC is invalid. | No | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
403 |
Managed-product, owner, role, share/inviter, or lifecycle sender permission is missing. | No | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
404 |
The owner-scoped calendar, event, person, resource, or invite target was not found. | No | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
500 |
Persistence, invitation, lifecycle, or internal calendar processing failed. | Yes | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
Related operations and events
- Operation
calendar_post_calendars - Operation
calendar_post_calendarsUnshare - Operation
calendar_get_calendarsAccessUUserUuidVVisibility} - Operation
calendar_get_calendarsResolveUuidUUserUuid}
Source trace
Repository: feradelinc/feradel.calendar.api
Route: routes/api/v1/calendar/routes.js
Handler: controller.share
Contract: OpenAPI 3.1, source-traced and publication-validated.