Skip to content
Reference
/
/
Grant access (create poli...

Grant access (create policy)

Request

🔒 Private label — contact sales. Requires a private-label entitlement on your API client.

Grant access (create policy)

Security
oauth2ClientCredentials(Required scopes: wallet-policies:write)
Headers
business_idstringrequired

Business identifier for the request

Bodyapplication/jsonrequired
subject_typestringrequired

Subject type

Enum:"EMPLOYEE""BUSINESS""EXTERNAL"
Example:"EMPLOYEE"
employee_idstring

Employee ID (required when subject_type is EMPLOYEE)

business_idstring

Business ID (required when subject_type is BUSINESS)

external_refstring

External reference (required when subject_type is EXTERNAL)

wallet_idstringrequired

Wallet ID to grant access to

permissionsArray of stringsrequired

Permission slugs to grant

Example:
[
  "view-balance",
  "view-transactions",
  "initiate-transfer"
]
limitsobject(PolicyLimitsDto)

Transaction limits

thresholdsobject(PolicyThresholdsDto)

Approval thresholds

restrictionsobject(PolicyRestrictionsDto)

Display restrictions

valid_fromstring

Policy start date (defaults to now)

valid_untilstring

Policy expiry date (null = no expiry)

granted_bystring

Employee ID of the granter (auto-populated from auth)

labelstring

Human-friendly label

Example:"Finance Team Member"
notesstring

Additional notes

curl -i -X POST \
  https://developer.boyahq.com/_mock/v2/openapi/wallet-policies \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'business_id: string' \
  -d '{
    "subject_type": "EMPLOYEE",
    "employee_id": "string",
    "business_id": "string",
    "external_ref": "string",
    "wallet_id": "string",
    "permissions": [
      "view-balance",
      "view-transactions",
      "initiate-transfer"
    ],
    "limits": {
      "per_transaction": 100000,
      "daily_total": 500000,
      "monthly_total": 2000000,
      "currency": "KES"
    },
    "thresholds": {
      "approval_required_above": 50000,
      "auto_flag_above": 200000
    },
    "restrictions": {
      "mask_balance": false,
      "mask_transaction_amounts": false,
      "max_transaction_history_days": 90
    },
    "valid_from": "string",
    "valid_until": "string",
    "granted_by": "string",
    "label": "Finance Team Member",
    "notes": "string"
  }'

Responses

Access granted successfully

Bodyapplication/json
_idstringrequired

Policy MongoDB ID

subject_typestringrequired

Subject type

Enum:"EMPLOYEE""BUSINESS""EXTERNAL"
employee_idobject

Employee reference (populated)

business_idstring

Business ID

external_refstring

External reference

wallet_idstringrequired

Wallet ID

permissionsArray of stringsrequired

Granted permissions

limitsobject(PolicyLimitsResponseDto)

Transaction limits

thresholdsobject(PolicyThresholdsResponseDto)

Approval thresholds

restrictionsobject(PolicyRestrictionsResponseDto)

Display restrictions

statusstringrequired

Policy status

Enum:"ACTIVE""SUSPENDED""EXPIRED""REVOKED"
valid_fromstring

Policy start date

valid_untilstring

Policy expiry date

granted_byobject

Granter employee reference

revoked_bystring

Revoker employee ID

revoked_atstring

Revocation timestamp

revoke_reasonstring

Revocation reason

labelstring

Human-friendly label

notesstring

Additional notes

createdAtstringrequired

Creation timestamp

updatedAtstringrequired

Last update timestamp

Response
{
  "_id": "string",
  "subject_type": "EMPLOYEE",
  "employee_id": {},
  "business_id": "string",
  "external_ref": "string",
  "wallet_id": "string",
  "permissions": [
    "string"
  ],
  "limits": {
    "per_transaction": {},
    "daily_total": {},
    "monthly_total": {},
    "currency": "string"
  },
  "thresholds": {
    "approval_required_above": {},
    "auto_flag_above": {}
  },
  "restrictions": {
    "mask_balance": true,
    "mask_transaction_amounts": true,
    "max_transaction_history_days": 0
  },
  "status": "ACTIVE",
  "valid_from": "string",
  "valid_until": "string",
  "granted_by": {},
  "revoked_by": "string",
  "revoked_at": "string",
  "revoke_reason": "string",
  "label": "string",
  "notes": "string",
  "createdAt": "string",
  "updatedAt": "string"
}