Custodian API (1.0.0)

Download OpenAPI specification:Download

Public API specification for the Custodian backend.

Authentication

Endpoints for user authentication and password management

Log in and obtain a JWT

Request Body schema: application/json

email required	string <email>
password	string <password> At least 8 characters, and 2 out of 4 of: lower case, upper case, symbols, numbers. Required if token is not provided.
token	string Single use login token received via email. Required if password is not provided.

Responses

Request samples

Payload

Content type

application/json

{"email": "alice@example.com",
"password": "secret",
"token": "550e8400-e29b-41d4-a716-446655440000"
}

Response samples

200
400
401
429

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Request a password reset email

Request Body schema: application/json

email

required

string <email>

Responses

Request samples

Payload

Content type

application/json

{"email": "alice@example.com"
}

Response samples

400
429

Content type

application/json

Example

missingFields

{"error": {"code": "BAD_REQUEST",
"message": "Missing email"
}
}

Change password

Authorizations:

bearerAuth

Request Body schema: application/json

old_password	string <password> Required if not logged in via login token.
new_password required	string <password> At least 8 characters, and 2 out of 4 of: lower case, upper case, symbols, numbers.

Responses

Request samples

Payload

Content type

application/json

{"old_password": "secret",
"new_password": "new_secret"
}

Response samples

400
401
429

Content type

application/json

Example

missingFields

{"error": {"code": "BAD_REQUEST",
"message": "Missing old_password or new_password"
}
}

User Profile

Endpoints for managing user profiles

Get currently authenticated user

Authorizations:

bearerAuth

Responses

Response samples

200
401
429

Content type

application/json

{"id": 0,
"email": "string"
}

Update currently authenticated user

After updating the email, the current authentication token should be discarded.

Authorizations:

bearerAuth

Request Body schema: application/json

email

required

string <email>

Responses

Request samples

Payload

Content type

application/json

{"email": "user@example.com"
}

Response samples

400
401
409
429

Content type

application/json

Example

missingFields

{"error": {"code": "BAD_REQUEST",
"message": "Email is required"
}
}

Get current user profile

Authorizations:

bearerAuth

Responses

Response samples

200
401
404
429

Content type

application/json

{"first_name": "Alice",
"last_name": "Doe",
"phone_number": "+32470123456",
"country": "BE",
"date_of_birth": "1990-01-01",
"language": "english",
"gender": "female"
}

Update current user profile

Authorizations:

bearerAuth

Request Body schema: application/json

first_name	string First name of the user. Cannot be empty if provided.
last_name	string Last name of the user. Cannot be empty if provided.
phone_number	string
country	string ISO 3166-1 alpha-2 country code
date_of_birth	string <date>
language	string Enum: "english" "dutch" "french"
gender	string Enum: "male" "female" "other" "prefer_not_to_say"

Responses

Request samples

Payload

Content type

application/json

{"first_name": "Alice",
"last_name": "Doe",
"phone_number": "+32470123456",
"country": "BE",
"date_of_birth": "1990-01-01",
"language": "english",
"gender": "female"
}

Response samples

400
401
429

Content type

application/json

{"error": {"code": "BAD_REQUEST",
"message": "Invalid language"
}
}

Get user profile by ID

Authorizations:

bearerAuth

path Parameters

userId

required

integer

Responses

Response samples

200
400
401
404
429

Content type

application/json

{"first_name": "Alice",
"last_name": "Doe",
"phone_number": "+32470123456",
"country": "BE",
"date_of_birth": "1990-01-01",
"language": "english",
"gender": "female"
}

Update user profile by ID

Authorizations:

bearerAuth

path Parameters

userId

required

integer

Request Body schema: application/json

first_name	string First name of the user. Cannot be empty if provided.
last_name	string Last name of the user. Cannot be empty if provided.
phone_number	string
country	string ISO 3166-1 alpha-2 country code
date_of_birth	string <date>
language	string Enum: "english" "dutch" "french"
gender	string Enum: "male" "female" "other" "prefer_not_to_say"

Responses

Request samples

Payload

Content type

application/json

{"first_name": "Alice",
"last_name": "Doe",
"phone_number": "+32470123456",
"country": "BE",
"date_of_birth": "1990-01-01",
"language": "english",
"gender": "female"
}

Response samples

400
401
429

Content type

application/json

Example

invalidUserId

{"error": {"code": "INVALID_USER_ID",
"message": "Invalid user ID"
}
}

Notifications

Endpoints for managing notification preferences

Get notification preferences for a channel

Authorizations:

bearerAuth

path Parameters

channel

required

string (NotificationChannel)

Enum: "app-push" "email"

Responses

Response samples

200
400
401
429

Content type

application/json

{"enabled": true,
"alerts": true,
"updates": true,
"reminders": true,
"newsletters": false,
"marketing": false
}

Update notification preferences for a channel

Authorizations:

bearerAuth

path Parameters

channel

required

string (NotificationChannel)

Enum: "app-push" "email"

Request Body schema: application/json

enabled	boolean
alerts	boolean
updates	boolean
reminders	boolean
newsletters	boolean
marketing	boolean

Responses

Request samples

Payload

Content type

application/json

{"enabled": true,
"alerts": true,
"updates": true,
"reminders": true,
"newsletters": false,
"marketing": false
}

Response samples

400
401
429

Content type

application/json

Example

invalidChannel

{"error": {"code": "INVALID_CHANNEL",
"message": "Invalid notification channel"
}
}

Logs

Endpoints for fetching user activity logs

Get activity logs for the current user

Authorizations:

bearerAuth

Responses

Response samples

200
401
429

Content type

application/json

[{"id": 1,
"user_id": 1,
"created": "2023-01-01T12:00:00",
"type": "auth/success",
"data": {"ip": "127.0.0.1",
"userAgent": "Mozilla/5.0"
}
}
]

Get activity logs for a specific user

Authorizations:

bearerAuth

path Parameters

userId

required

integer

Responses

Response samples

200
400
401
429

Content type

application/json

[{"id": 1,
"user_id": 1,
"created": "2023-01-01T12:00:00",
"type": "auth/success",
"data": {"ip": "127.0.0.1",
"userAgent": "Mozilla/5.0"
}
}
]

Development

Endpoints for development and testing purposes only

Create a user (dev only)

Request Body schema: application/json

email required	string
password required	string <password> At least 8 characters, and 2 out of 4 of: lower case, upper case, symbols, numbers.

Responses

Request samples

Payload

Content type

application/json

{"email": "newuser@example.com",
"password": "password123"
}

Response samples

400
429
500

Content type

application/json

Example

missingFields

{"error": {"code": "BAD_REQUEST",
"message": "Missing email or password"
}
}

Get user rate limit settings (dev only)

path Parameters

userId

required

integer

Responses

Response samples

200
400
404
429

Content type

application/json

{"window_seconds": 60,
"requests_per_window": 30
}

Set user rate limit settings (dev only)

path Parameters

userId

required

integer

Request Body schema: application/json

window_seconds required	integer
requests_per_window required	integer

Responses

Request samples

Payload

Content type

application/json

{"window_seconds": 60,
"requests_per_window": 30
}

Response samples

400
429

Content type

application/json

{"error": {"code": "INVALID_CREDENTIALS",
"message": "User not found"
}
}

Remove user rate limit settings (dev only)

path Parameters

userId

required

integer

Responses

Response samples

400
429

Content type

application/json

{"error": {"code": "INVALID_CREDENTIALS",
"message": "User not found"
}
}

Reset all rate limit counters (dev only)

Responses

Response samples

429
500

Content type

application/json

{"error": {"code": "TOO_MANY_REQUESTS",
"message": "Too many requests"
}
}

Health

Health check endpoint

Health check

Responses

Response samples

200
503

Content type

application/json

{"status": "UP",
"checks": [{"id": "redis",
"status": "UP"
},
{"id": "mariadb",
"status": "UP"
}
]
}