Providentia API (1.4.1)

Download OpenAPI specification:

The HTTP contract that the Providentia template expects from a backend when it runs in http mode (provideApi({ mode: 'http', baseUrl })).

This document was generated from the code: the operations come from the *.api.http.ts implementations and the JSON shapes mirror the TypeScript interfaces in src/app/**/*.models.ts and src/app/core/models/*.ts.

Authentication: every request to the base URL carries Authorization: Bearer <token> (added by the auth interceptor). Errors are JSON { "message": "..." } with a 4xx/5xx status; the message is shown to the user as is.

Roles: every workspace member has a role (owner, admin, member, viewer). The UI hides what a role may not do (see src/app/core/auth/permissions.ts), but the backend must enforce the same rules and answer 403 otherwise. Operations below list the permission they require.

Auth

Sign in, sign up and password reset.

Sign in with email and password

Request Body schema: application/json
required
email
required
string <email>
password
required
string <password>
remember
required
boolean

Responses

Request samples

Content type
application/json
{
  • "email": "ada@acme.test",
  • "password": "demo-password",
  • "remember": true
}

Response samples

Content type
application/json
{
  • "token": "demo-token",
  • "expiresAt": "2026-12-01T09:00:00Z",
  • "user": {
    }
}

Create an account and sign in

Request Body schema: application/json
required
name
required
string
company
required
string
email
required
string <email>
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "company": "string",
  • "email": "user@example.com",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "token": "demo-token",
  • "expiresAt": "2026-12-01T09:00:00Z",
  • "user": {
    }
}

Sign out

Sent with an empty JSON body ({}).

Authorizations:
bearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Request a password reset email

Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "Enter a valid email address."
}

Set a new password with a reset token

Request Body schema: application/json
required
token
required
string

Token from the reset link.

password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "message": "Something went wrong."
}

Notifications

In-app notifications.

List notifications

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark notifications as read

Authorizations:
bearerAuth
Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Onboarding

First-run setup wizard.

Complete the onboarding wizard

Authorizations:
bearerAuth
Request Body schema: application/json
required
workspace
required
string
teamSize
required
string (TeamSize)
Enum: "1-10" "11-50" "51-200" "200+"
goals
required
Array of strings (OnboardingGoal)
Items Enum: "mrr" "churn" "cohorts" "reporting" "pricing"
dataSource
required
string (DataSource)
Enum: "billing-api" "csv" "sample"
invites
required
Array of strings

Teammate emails to invite; empty strings are ignored.

Responses

Request samples

Content type
application/json
{
  • "workspace": "Acme Demo",
  • "teamSize": "11-50",
  • "goals": [
    ],
  • "dataSource": "sample",
  • "invites": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Overview

Dashboard KPIs and charts.

Get the data of the Overview page

Authorizations:
bearerAuth
query Parameters
range
required
string (OverviewRange)
Enum: "3m" "6m" "12m" "24m"

Time range to cover.

Responses

Response samples

Content type
application/json
{
  • "kpis": [
    ],
  • "mrr": [
    ],
  • "movements": [
    ],
  • "plans": [
    ],
  • "activeUsers": [
    ],
  • "activeUsersGranularity": "day",
  • "cohorts": [
    ],
  • "recentSignups": [
    ]
}

Users

Customer accounts.

List users (paginated)

Filters equal to an empty string or all are not sent by the client. sort and direction come from the UserQuery.sort object ({ field, direction }).

Authorizations:
bearerAuth
query Parameters
search
string

Free-text search on name, email and company.

plan
string (PlanId)
Enum: "starter" "growth" "scale" "enterprise"

Subscription plans of the product.

status
string (UserStatus)
Enum: "active" "trialing" "past_due" "churned"
country
string
Example: country=DE
sort
string (UserSortField)
Enum: "name" "plan" "status" "mrr" "signedUpAt" "lastActiveAt"

Field to sort by.

direction
string (SortDirection)
Enum: "asc" "desc"

Sort direction, sent together with sort.

page
integer >= 1
Default: 1

1-based page number.

pageSize
integer >= 1
Example: pageSize=10

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0,
  • "statusCounts": {
    },
  • "countries": [
    ]
}

Export all users matching the filters

Same filters as GET /users, without pagination.

Authorizations:
bearerAuth
query Parameters
search
string

Free-text search on name, email and company.

plan
string (PlanId)
Enum: "starter" "growth" "scale" "enterprise"

Subscription plans of the product.

status
string (UserStatus)
Enum: "active" "trialing" "past_due" "churned"
country
string
Example: country=DE
sort
string (UserSortField)
Enum: "name" "plan" "status" "mrr" "signedUpAt" "lastActiveAt"

Field to sort by.

direction
string (SortDirection)
Enum: "asc" "desc"

Sort direction, sent together with sort.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a customer account on a free trial

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
email
required
string <email>
company
required
string
plan
required
string (PlanId)
Enum: "starter" "growth" "scale" "enterprise"

Subscription plans of the product.

country
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "company": "string",
  • "plan": "starter",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "id": "usr_1001",
  • "name": "Ada Demo",
  • "email": "ada@acme.test",
  • "company": "Acme Demo",
  • "plan": "growth",
  • "status": "active",
  • "seats": 12,
  • "mrr": 99,
  • "country": "DE",
  • "signedUpAt": "2026-01-15T10:00:00Z",
  • "lastActiveAt": "2026-11-12T16:45:00Z"
}

Delete users in bulk

Authorizations:
bearerAuth
Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Update an account

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
email
string <email>
company
string
plan
string (PlanId)
Enum: "starter" "growth" "scale" "enterprise"

Subscription plans of the product.

status
string (UserStatus)
Enum: "active" "trialing" "past_due" "churned"
seats
integer
country
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "company": "string",
  • "plan": "starter",
  • "status": "active",
  • "seats": 0,
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "id": "usr_1001",
  • "name": "Ada Demo",
  • "email": "ada@acme.test",
  • "company": "Acme Demo",
  • "plan": "growth",
  • "status": "active",
  • "seats": 12,
  • "mrr": 99,
  • "country": "DE",
  • "signedUpAt": "2026-01-15T10:00:00Z",
  • "lastActiveAt": "2026-11-12T16:45:00Z"
}

Reports

Report builder and saved reports.

Compute a report

Authorizations:
bearerAuth
Request Body schema: application/json
required
metric
required
string (ReportMetric)
Enum: "mrr" "netNewMrr" "newMrr" "churnedMrr" "customers" "arpu" "churnRate"
groupBy
required
string (ReportGrouping)
Enum: "month" "quarter"
range
required
string (ReportRange)
Enum: "6m" "12m" "24m"
breakdown
required
string (ReportBreakdown)
Enum: "none" "plan"
chart
required
string (ReportChartType)
Enum: "line" "bar"

Responses

Request samples

Content type
application/json
{
  • "metric": "mrr",
  • "groupBy": "month",
  • "range": "12m",
  • "breakdown": "none",
  • "chart": "line"
}

Response samples

Content type
application/json
{
  • "definition": {
    },
  • "series": [
    ],
  • "rows": [
    ],
  • "headline": 0,
  • "change": 0
}

List saved reports

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Save a new report

Used by save() when the request has no id.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
required
object (ReportDefinition)

Everything needed to compute a report. Saved reports store exactly this.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "definition": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "definition": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a saved report

Used by save() when the request has an id (the id is sent in the path, not in the body).

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
required
string
required
object (ReportDefinition)

Everything needed to compute a report. Saved reports store exactly this.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "definition": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "definition": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a saved report

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Billing

Subscription, payment method and invoices.

Get subscription, usage, payment method, invoices and plans

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    },
  • "usage": [
    ],
  • "paymentMethod": {
    },
  • "invoices": [
    ],
  • "plans": [
    ]
}

Change plan and billing cycle

Authorizations:
bearerAuth
Request Body schema: application/json
required
plan
required
string (PlanId)
Enum: "starter" "growth" "scale" "enterprise"

Subscription plans of the product.

cycle
required
string (BillingCycle)
Enum: "monthly" "yearly"

Responses

Request samples

Content type
application/json
{
  • "plan": "starter",
  • "cycle": "monthly"
}

Response samples

Content type
application/json
{
  • "plan": "growth",
  • "cycle": "monthly",
  • "amount": 99,
  • "status": "active",
  • "currentPeriodEnd": "2026-12-01T00:00:00Z",
  • "cancelAtPeriodEnd": false
}

Cancel or resume the subscription at the end of the period

Authorizations:
bearerAuth
Request Body schema: application/json
required
cancelAtPeriodEnd
required
boolean

Responses

Request samples

Content type
application/json
{
  • "cancelAtPeriodEnd": true
}

Response samples

Content type
application/json
{
  • "plan": "growth",
  • "cycle": "monthly",
  • "amount": 99,
  • "status": "active",
  • "currentPeriodEnd": "2026-12-01T00:00:00Z",
  • "cancelAtPeriodEnd": false
}

Replace the payment method

The demo form sends the card number so the mock stays self-contained. In production, collect the card with your payment provider's hosted fields and send the token it returns instead, so card data never touches your server.

Authorizations:
bearerAuth
Request Body schema: application/json
required
cardNumber
required
string
expMonth
required
integer [ 1 .. 12 ]
expYear
required
integer
billingEmail
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "cardNumber": "string",
  • "expMonth": 1,
  • "expYear": 0,
  • "billingEmail": "user@example.com"
}

Response samples

Content type
application/json
{
  • "brand": "visa",
  • "last4": "4242",
  • "expMonth": 1,
  • "expYear": 0,
  • "billingEmail": "user@example.com"
}

Download an invoice as PDF

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Settings

Profile, notification preferences and security of the signed-in user.

Get the profile of the signed-in user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "Ada Demo",
  • "email": "ada@acme.test",
  • "company": "Acme Demo",
  • "jobTitle": "Head of Finance",
  • "timezone": "Europe/Berlin",
  • "language": "en"
}

Replace the profile

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
email
required
string <email>
company
required
string
jobTitle
required
string
timezone
required
string
language
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Ada Demo",
  • "email": "ada@acme.test",
  • "company": "Acme Demo",
  • "jobTitle": "Head of Finance",
  • "timezone": "Europe/Berlin",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "name": "Ada Demo",
  • "email": "ada@acme.test",
  • "company": "Acme Demo",
  • "jobTitle": "Head of Finance",
  • "timezone": "Europe/Berlin",
  • "language": "en"
}

Upload the avatar

The client sends a 256x256 JPEG as the avatar field (file name avatar.jpg).

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
avatar
required
string <binary>

Avatar image (JPEG, 256x256).

Responses

Response samples

Content type
application/json

Remove the avatar

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Get notification preferences

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "weeklyReport": true,
  • "churnAlerts": true,
  • "paymentFailures": true,
  • "newSignups": true,
  • "productUpdates": true,
  • "churnAlertThreshold": 0,
  • "channel": "email"
}

Replace notification preferences

Authorizations:
bearerAuth
Request Body schema: application/json
required
weeklyReport
required
boolean
churnAlerts
required
boolean
paymentFailures
required
boolean
newSignups
required
boolean
productUpdates
required
boolean
churnAlertThreshold
required
number

Threshold (MRR, USD) above which churn alerts fire.

channel
required
string
Enum: "email" "slack" "both"

Responses

Request samples

Content type
application/json
{
  • "weeklyReport": true,
  • "churnAlerts": true,
  • "paymentFailures": true,
  • "newSignups": true,
  • "productUpdates": true,
  • "churnAlertThreshold": 0,
  • "channel": "email"
}

Response samples

Content type
application/json
{
  • "weeklyReport": true,
  • "churnAlerts": true,
  • "paymentFailures": true,
  • "newSignups": true,
  • "productUpdates": true,
  • "churnAlertThreshold": 0,
  • "channel": "email"
}

Get two-factor status and active sessions

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "twoFactorEnabled": true,
  • "sessions": [
    ]
}

Change the password

Authorizations:
bearerAuth
Request Body schema: application/json
required
current
required
string <password>
next
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "current": "pa$$word",
  • "next": "pa$$word"
}

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Enable or disable two-factor authentication

Authorizations:
bearerAuth
Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "twoFactorEnabled": true,
  • "sessions": [
    ]
}

Revoke an active session

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "twoFactorEnabled": true,
  • "sessions": [
    ]
}

Team

Members of the workspace, their roles and pending invitations.

Get members, pending invitations and seat usage

Every member can read the team.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Invite a person to the workspace

Takes a seat until the invitation is accepted or revoked. Ownership cannot be granted by invitation.

Authorizations:
bearerAuth
Request Body schema: application/json
required
email
required
string <email>
role
required
string (AssignableRole)
Enum: "admin" "member" "viewer"

Any role except owner.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Send the invitation again and renew its expiry

Authorizations:
bearerAuth
path Parameters
id
required
string

Member or invitation id.

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Revoke a pending invitation

Authorizations:
bearerAuth
path Parameters
id
required
string

Member or invitation id.

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Change a member's role

The owner's role cannot be changed and nobody can be made owner here.

Authorizations:
bearerAuth
path Parameters
id
required
string

Member or invitation id.

Request Body schema: application/json
required
role
required
string (AssignableRole)
Enum: "admin" "member" "viewer"

Any role except owner.

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Remove a member from the workspace

Frees their seat. The owner cannot be removed.

Authorizations:
bearerAuth
path Parameters
id
required
string

Member or invitation id.

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Developers

API keys and webhook endpoints of the workspace.

Get API keys and webhook endpoints

Every member can read them. Secrets are never included, only the key prefix.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Create an API key

The full secret is returned only in this response; only its first 12 characters are kept. At most 10 keys per workspace.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 40 ] characters
access
required
string (ApiKeyAccess)
Enum: "read" "write"
expiresInDays
required
integer or null
Enum: 30 90 365 null

Null = the key does not expire.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "access": "read",
  • "expiresInDays": 30
}

Response samples

Content type
application/json
{
  • "developers": {
    },
  • "secret": "pk_live_3fA9xK2mQ7vLw0ZpR8dTn5BcY1hGe4Sj"
}

Revoke an API key

Apps using the key stop working immediately.

Authorizations:
bearerAuth
path Parameters
id
required
string

API key id.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Add a webhook endpoint

The endpoint starts enabled. At most 5 endpoints per workspace.

Authorizations:
bearerAuth
Request Body schema: application/json
required
url
required
string <uri>

Must be an https:// URL.

description
required
string
events
required
Array of strings (WebhookEvent) non-empty
Items Enum: "customer.created" "customer.updated" "subscription.created" "subscription.updated" "subscription.canceled" "invoice.paid" "invoice.payment_failed" "team.member_added"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Edit or enable/disable a webhook endpoint

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

Request Body schema: application/json
required
url
string <uri>
description
string
events
Array of strings (WebhookEvent) non-empty
Items Enum: "customer.created" "customer.updated" "subscription.created" "subscription.updated" "subscription.canceled" "invoice.paid" "invoice.payment_failed" "team.member_added"
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "events": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Delete a webhook endpoint

Its delivery history is removed too.

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Send a test event to an endpoint

Sends a customer.created test event and records the delivery.

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "event": "customer.created",
  • "status": "succeeded",
  • "statusCode": 200,
  • "durationMs": 0,
  • "at": "2019-08-24T14:15:22Z"
}

List the recent deliveries of an endpoint

Newest first, at most 20. Every member can read them.

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Send a past delivery again

Creates a new delivery for the same event.

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

deliveryId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "event": "customer.created",
  • "status": "succeeded",
  • "statusCode": 200,
  • "durationMs": 0,
  • "at": "2019-08-24T14:15:22Z"
}