Auth guard: admin-api-key header required for all endpoints. No JWT or partner key access.

​
Overview

An account provider is a financial or health institution (e.g. a bank, HSA custodian, or insurer) that can be linked to user accounts. Providers are global configuration managed exclusively by platform administrators.
  • Name uniqueness is global. No two providers may share the same name.
  • Delete is guarded. A provider with associated accounts cannot be deleted.

​
Data Flow

​
Auth Guards by Endpoint

EndpointAdmin keyNotes
POST /account_providers✓Name must be unique
GET /account_providers✓Filter by status
GET /account_providers/{id}✓
PATCH /account_providers/{id}✓name and/or status updatable
DELETE /account_providers/{id}✓Blocked if accounts exist

​
Endpoints

POST /account_providers

Create a new account provider. Name must be unique.

GET /account_providers

Paginated list. Filter by status.

GET /account_providers/{id}

Fetch a single provider by UUID.

PATCH /account_providers/{id}

Update name or status. New name must not conflict.

DELETE /account_providers/{id}

Delete provider. Returns 409 if it has associated accounts.

​
Request / Response Examples

curl -X POST http://localhost:8080/account_providers \
  -H 'admin-api-key: your-admin-key' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "HDFC Bank" }'

​
Error Codes

CodeHTTPDescription
APE-700500Internal server error
APE-701404Account provider not found
APE-702409Name already exists
APE-703409Provider has associated accounts — delete accounts first
APE-704400Validation error (e.g. empty name)