Herald
OpenapiExt

Grant points to a user account (SDK)

Grants points to a user's account from a third-party application. Returns transaction details including the new balance. # Authentication Requires valid API Key via X-API-Key header # Realm Isolation The API key must belong to the same realm as the requested realm. Cross-realm requests will return 403 Forbidden. # Example ```bash curl -X POST \ https://api.example.com/api/ext/points/realm123/grant \ -H "X-API-Key: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "userId": "user-123", "amount": 100, "reason": "Promotional grant" }' ```

POST
/api/ext/points/{realmId}/grant

Grants points to a user's account from a third-party application. Returns transaction details including the new balance.

Authentication

Requires valid API Key via X-API-Key header

Realm Isolation

The API key must belong to the same realm as the requested realm. Cross-realm requests will return 403 Forbidden.

Example

curl -X POST \  https://api.example.com/api/ext/points/realm123/grant \  -H "X-API-Key: your-api-key" \  -H "Content-Type: application/json" \  -d '{    "userId": "user-123",    "amount": 100,    "reason": "Promotional grant"  }'

Authorization

api_key
X-API-Key<token>

Client-app API key (third-party external API).

In: header

Path Parameters

realmId*string

Realm ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount*integer
Formatint64
bucketId?|

Required target Credit Bucket. Deserialized as Option so a missing field yields a structured 400 grant_bucket_required body instead of Axum's generic JSON parse error.

reason*string
userId*string
validityDays?|
Formatint64

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/ext/points/string/grant" \  -H "Content-Type: application/json" \  -d '{    "amount": 0,    "reason": "string",    "userId": "string"  }'
{  "amount": 0,  "balance": 0,  "bucketId": "string",  "expiresAt": "string",  "grantedBalance": 0,  "transactionId": "string",  "userId": "string"}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}