Organization and Billing Endpoints

Organizations (Multi-tenant)

Organizations represent tenants in SecuFile's SaaS model. Each organization has its own users, files, encryption keys, and S3 bucket.

GET /api/v1/organizations

List organizations accessible to the current user.

POST /api/v1/organizations

Create a new organization. This automatically triggers:

Dedicated OVH S3 bucket creation
RSA-4096 key pair generation
Stripe customer creation
Default plan assignment (free)
Default folder creation (uploads, transfert, Data)

{
  "name": "My Organization",
  "type": "client",
  "parent_msp_id": "uuid"
}

GET /api/v1/organizations/:org_id

Get organization details.

PATCH /api/v1/organizations/:org_id

Update an organization.

DELETE /api/v1/organizations/:org_id

Delete an organization (soft delete recommended).

Organization User Management

Method	Endpoint	Description
GET	`/organizations/:org_id/users`	List users
POST	`/organizations/:org_id/users`	Add a user
PATCH	`/organizations/:org_id/users/:user_id`	Update user role
DELETE	`/organizations/:org_id/users/:user_id`	Remove a user
POST	`/organizations/:org_id/users/:user_id/reset-password`	Reset user password

Organization Storage

Method	Endpoint	Description
GET	`/organizations/:org_id/storage`	Get storage config
POST	`/organizations/:org_id/storage`	Create storage config
POST	`/organizations/:org_id/storage/provision`	Provision S3 bucket
DELETE	`/organizations/:org_id/storage`	Delete storage config
GET	`/organizations/:org_id/storage/status`	Get storage status

Organization Notifications

Method	Endpoint	Description
GET	`/organizations/:org_id/notification-config`	Get notification config
PUT	`/organizations/:org_id/notification-config`	Update notification config
POST	`/organizations/:org_id/notification-config/test-email`	Test email connection
POST	`/organizations/:org_id/notification-config/test-sms`	Test SMS connection
GET	`/organizations/:org_id/notification-logs`	Get notification logs

Method	Endpoint	Description
GET	`/organizations/:org_id/settings/consent-text`	Get Loi 25 consent text
PUT	`/organizations/:org_id/settings/consent-text`	Update consent text

Subscriptions

GET /api/v1/organizations/:org_id/subscription

Get the organization's active subscription.

{
  "id": "uuid",
  "plan_id": "uuid",
  "plan_name": "Pro",
  "status": "active",
  "current_period_start": "2026-02-01T00:00:00Z",
  "current_period_end": "2026-03-01T00:00:00Z",
  "stripe_subscription_id": "sub_xxxx"
}

POST /api/v1/organizations/:org_id/subscription/change

Change subscription plan. Handles Stripe prorations automatically.

{
  "plan_id": "uuid"
}

POST /api/v1/organizations/:org_id/subscription/cancel

Cancel subscription (effective at end of period).

POST /api/v1/organizations/:org_id/subscription/reactivate

Reactivate a cancelled subscription (before period end).

Pricing Plans

GET /api/v1/plans (public)

List available plans.

{
  "plans": [
    {
      "id": "uuid",
      "name": "Free",
      "code": "free",
      "storage_limit_bytes": 104857600,
      "price_monthly": 0,
      "price_yearly": 0,
      "features": ["100 MB storage", "1 user"],
      "is_public": true
    },
    {
      "id": "uuid",
      "name": "Pro",
      "code": "pro",
      "storage_limit_bytes": 10737418240,
      "price_monthly": 1999,
      "price_yearly": 19990,
      "features": ["10 GB storage", "10 users", "E2E encryption"],
      "is_public": true
    }
  ]
}

Invoices

Method	Endpoint	Description
GET	`/organizations/:org_id/invoices`	List invoices
GET	`/organizations/:org_id/invoices/:id`	Invoice details
GET	`/organizations/:org_id/invoices/:id/pdf`	Download PDF
POST	`/organizations/:org_id/invoices/:id/pay`	Mark as paid
POST	`/organizations/:org_id/invoices/:id/void`	Void an invoice
POST	`/organizations/:org_id/invoices/:id/finalize`	Finalize an invoice

Payment Methods

Method	Endpoint	Description
GET	`/organizations/:org_id/payment-methods`	List methods
POST	`/organizations/:org_id/payment-methods`	Add (via Stripe)
GET	`/organizations/:org_id/payment-methods/:id`	Get details
DELETE	`/organizations/:org_id/payment-methods/:id`	Delete
POST	`/organizations/:org_id/payment-methods/:id/default`	Set as default

Invitations

Method	Endpoint	Description
GET	`/organizations/:org_id/invitations`	List invitations
POST	`/organizations/:org_id/invitations`	Create invitation
GET	`/organizations/:org_id/invitations/:id`	Get invitation
DELETE	`/organizations/:org_id/invitations/:id`	Delete invitation
POST	`/organizations/:org_id/invitations/:id/revoke`	Revoke
POST	`/organizations/:org_id/invitations/:id/resend`	Resend email

Public invitation routes (no auth):

Method	Endpoint	Description
GET	`/api/v1/invitations/:token`	Get invitation by token
POST	`/api/v1/invitations/:token/accept`	Accept invitation

Coupons

Method	Endpoint	Description
GET	`/api/v1/coupons`	List coupons
POST	`/api/v1/coupons`	Create coupon
GET	`/api/v1/coupons/:id`	Get coupon
PATCH	`/api/v1/coupons/:id`	Update coupon
DELETE	`/api/v1/coupons/:id`	Delete coupon
POST	`/api/v1/coupons/validate`	Validate a coupon code
POST	`/api/v1/coupons/:code/redeem`	Redeem a coupon

Usage Metering

Method	Endpoint	Description
GET	`/organizations/:org_id/usage`	Current usage
GET	`/organizations/:org_id/usage/history`	Usage history
GET	`/organizations/:org_id/usage/summary`	Usage summary

Stripe Webhooks

POST /api/v1/webhooks/stripe

Receives and processes Stripe events. Signature verification is performed internally. The stripe_events_processed table ensures idempotency.

Events processed:

customer.subscription.*: Subscription updates
invoice.*: Invoice updates
payment_method.*: Payment method updates
charge.*: Charge tracking

Organization and Billing Endpoints

On this page