Wallet Core Admin

Overview

Platform admin endpoints for managing accounts across tenants. These endpoints require admin JWT authentication and are not subject to tenant entitlements.

Authentication Context

Understanding how admin vs tenant context works for account endpoints.

Context	Auth Type	Tenant Scope	Behavior
Admin JWT	Bearer token	Optional	Full access to all tenants. Tenant ID is an optional filter, not a restriction.
Tenant User	Bearer token	Required	Scoped to own tenant only. Subject to tenant entitlements.
API Key	X-API-Key header	Required	Scoped to tenant that owns the key. Subject to entitlements.

Key Differences

Admin endpoints bypass tenant entitlement checks. When an admin JWT calls tenant endpoints, entitlements are bypassed. For tenant-scoped admin routes (/admin/tenants/:tenantID/...), the path parameter determines scope, not the JWT's tenant context.

List All Accounts

Retrieve accounts across all tenants with optional filtering.

Endpoint

GET/api/v1/admin/accounts

List all accounts across the platform. Admin JWT required. Supports filtering by tenant, status, and pagination.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	No	Filter by tenant UUID
`status`	string	No	Filter by account statusValues: active, blocked, closed
`account_type`	string	No	Filter by account typeValues: savings, current, wallet
`search`	string	No	Search by account number or holder name
`limit`	integer	No (default: 20)	Page size (max 100)
`offset`	integer	No (default: 0)	Page offset

Response- Paginated list of accounts

json

{
  "accounts": [
    {
      "account_id": "acc_550e8400-e29b-41d4-a716-446655440000",
      "account_number": "1234567890",
      "account_type": "savings",
      "status": "active",
      "balance": "50000.00",
      "currency": "NGN",
      "holder_name": "John Doe",
      "tenant_id": "tenant_660e8400-e29b-41d4-a716-446655440001",
      "tenant_name": "Acme Corp",
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-14T12:30:00Z"
    }
  ],
  "total": 1250,
  "limit": 20,
  "offset": 0
}

Error Responses

Status	Code	Description
401	`unauthorized`	Missing or invalid admin JWT
403	`forbidden`	Admin role required

Account Metrics

Platform-wide account creation and status metrics.

Endpoint

GET/api/v1/admin/accounts/metrics

Get aggregated account metrics across all tenants. Useful for platform analytics and dashboards.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	No	Filter metrics by tenant UUID
`start_date`	string	No	Start date for metrics period (ISO 8601)
`end_date`	string	No	End date for metrics period (ISO 8601)
`granularity`	string	No (default: day)	Time granularity for time-series dataValues: hour, day, week, month

Response- Account metrics summary

json

{
  "summary": {
    "total_accounts": 125000,
    "active_accounts": 118500,
    "blocked_accounts": 4200,
    "closed_accounts": 2300
  },
  "by_type": {
    "savings": 75000,
    "current": 35000,
    "wallet": 15000
  },
  "creation_trend": [
    {
      "date": "2025-01-13",
      "count": 450
    },
    {
      "date": "2025-01-14",
      "count": 520
    }
  ],
  "top_tenants": [
    {
      "tenant_id": "tenant_660e8400-e29b-41d4-a716-446655440001",
      "tenant_name": "Acme Corp",
      "account_count": 45000
    }
  ]
}

Error Responses

Status	Code	Description
401	`unauthorized`	Missing or invalid admin JWT
403	`forbidden`	Admin role required

List Tenant Accounts

List accounts for a specific tenant.

Endpoint

GET/api/v1/admin/tenants/{tenantID}/accounts

List all accounts belonging to a specific tenant. The tenant is identified by the path parameter, not the admin's JWT context.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Path Parameters

Parameter	Type	Required	Description
`tenantID`	string	Yes	UUID of the tenant

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by account statusValues: active, blocked, closed
`account_type`	string	No	Filter by account type
`search`	string	No	Search by account number or holder name
`limit`	integer	No (default: 20)	Page size
`offset`	integer	No (default: 0)	Page offset

Response- Paginated list of tenant accounts

json

{
  "accounts": [
    {
      "account_id": "acc_550e8400-e29b-41d4-a716-446655440000",
      "account_number": "1234567890",
      "account_type": "savings",
      "status": "active",
      "balance": "50000.00",
      "currency": "NGN",
      "holder_name": "John Doe",
      "created_at": "2025-01-10T08:00:00Z"
    }
  ],
  "total": 450,
  "limit": 20,
  "offset": 0
}

Error Responses

Status	Code	Description
401	`unauthorized`	Missing or invalid admin JWT
403	`forbidden`	Admin role required
404	`tenant_not_found`	Tenant does not exist

Block Account

Block or freeze an account to prevent transactions.

Endpoint

PUT/api/v1/admin/tenants/{tenantID}/accounts/{accountID}/block

Block an account. Blocked accounts cannot perform any transactions but remain in the system. This action is reversible via unblock.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
`tenantID`	string	Yes	UUID of the tenant
`accountID`	string	Yes	UUID of the account to block

Request Body- Block reason and metadata

json

{
  "reason": "Suspicious activity detected",
  "notes": "Multiple failed transaction attempts from unusual locations",
  "notify_holder": true
}

Response- Account blocked successfully

json

{
  "account_id": "acc_550e8400-e29b-41d4-a716-446655440000",
  "status": "blocked",
  "blocked_at": "2025-01-14T15:30:00Z",
  "blocked_by": "admin_770e8400-e29b-41d4-a716-446655440002",
  "reason": "Suspicious activity detected"
}

Error Responses

Status	Code	Description
400	`already_blocked`	Account is already blocked
400	`account_closed`	Cannot block a closed account
404	`account_not_found`	Account not found or does not belong to tenant

Request Body Parameters

Field	Type	Required	Description
reason	string	Yes	Reason for blocking the account
notes	string	No	Additional internal notes
notify_holder	boolean	No	Send notification to account holder (default: false)

Unblock Account

Restore a blocked account to active status.

Endpoint

PUT/api/v1/admin/tenants/{tenantID}/accounts/{accountID}/unblock

Unblock a previously blocked account. The account will return to active status and can resume transactions.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
`tenantID`	string	Yes	UUID of the tenant
`accountID`	string	Yes	UUID of the account to unblock

Request Body- Unblock reason and metadata

json

{
  "reason": "Investigation completed - no fraud detected",
  "notes": "Customer verified identity via support call",
  "notify_holder": true
}

Response- Account unblocked successfully

json

{
  "account_id": "acc_550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "unblocked_at": "2025-01-14T16:00:00Z",
  "unblocked_by": "admin_770e8400-e29b-41d4-a716-446655440002",
  "reason": "Investigation completed - no fraud detected"
}

Error Responses

Status	Code	Description
400	`not_blocked`	Account is not currently blocked
400	`account_closed`	Cannot unblock a closed account
404	`account_not_found`	Account not found or does not belong to tenant

Request Body Parameters

Field	Type	Required	Description
reason	string	Yes	Reason for unblocking the account
notes	string	No	Additional internal notes
notify_holder	boolean	No	Send notification to account holder (default: false)

Close Account

Permanently close an account. This action is irreversible.

Endpoint

PUT/api/v1/admin/tenants/{tenantID}/accounts/{accountID}/close

Close an account permanently. The account balance must be zero before closing. This action cannot be reversed.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
`tenantID`	string	Yes	UUID of the tenant
`accountID`	string	Yes	UUID of the account to close

Request Body- Closure reason and metadata

json

{
  "reason": "Customer requested account closure",
  "notes": "Verified via support ticket #12345",
  "notify_holder": true,
  "force": false
}

Response- Account closed successfully

json

{
  "account_id": "acc_550e8400-e29b-41d4-a716-446655440000",
  "status": "closed",
  "closed_at": "2025-01-14T17:00:00Z",
  "closed_by": "admin_770e8400-e29b-41d4-a716-446655440002",
  "reason": "Customer requested account closure"
}

Error Responses

Status	Code	Description
400	`balance_not_zero`	Account balance must be zero before closing
400	`pending_transactions`	Account has pending transactions
400	`already_closed`	Account is already closed
404	`account_not_found`	Account not found or does not belong to tenant

Request Body Parameters

Field	Type	Required	Description
reason	string	Yes	Reason for closing the account
notes	string	No	Additional internal notes
notify_holder	boolean	No	Send notification to account holder (default: false)
force	boolean	No	Force close even with non-zero balance (requires super_admin role)

Documentation

Platform Admin Accounts

Overview

Authentication Context

Key Differences

List All Accounts

Endpoint

Account Metrics

Endpoint

List Tenant Accounts

Endpoint

Block Account

Endpoint

Request Body Parameters

Unblock Account

Endpoint

Request Body Parameters

Close Account

Endpoint

Request Body Parameters