Users

Server

List, create and edit users; suspend, credit, 2FA reset and per-user history.

List users

GET

https://ai.brandkamu.id/api/admin

/users

Lists and searches users. Results are ordered by sort, then by id.

List users › query Parameters

q

string

Case-insensitive substring of the email or name.

status

string · enum

active (not disabled and email verified), disabled, unverified (not disabled, email not verified) or admin. All users when absent.

Enum values:

active

disabled

unverified

admin

sort

string · enum

Enum values:

newest

oldest

balance_desc

balance_asc

last_login

Default: newest

limit

integer · min: 1 · max: 200

Page size (clamped to 1-200).

Default: 50

offset

integer · min: 0

Rows to skip.

Default: 0

List users › Responses

A page of users.

User[] · required

total

integer · required

Users matching the filters.

Create a user

POST

https://ai.brandkamu.id/api/admin

/users

Creates a regular user with a password. The email is marked as verified. Only is_admin: false is accepted: the initial admin is the only admin (403 otherwise).

Create a user › Request Body

email

string · email · maxLength: 254 · required

Stored lower-cased.

password

string · minLength: 8 · required

name

string

Default:

is_admin

boolean

Must be false.

Default: false

balance_nano

integer · int64 · min: 0

Starting credit in nano-USD (1 USD = 1_000_000_000).

Default: 0

Create a user › Responses

The new user.

User

id

string · uuid · required

email

string · required

name

string · required

is_admin

boolean · required

is_owner

boolean · required

The initial admin; can't lose the admin role or be suspended.

balance_nano

integer · int64 · required

Balance in nano-USD (1 USD = 1_000_000_000); can be negative.

disabled_at

string | null · date-time · required

Set while the account is suspended.

disabled_reason

string | null · required

last_login_at

string | null · date-time · required

mfa_enabled

boolean · required

email_verified

boolean · required

created_at

string · date-time · required

POST/users

curl https://ai.brandkamu.id/api/admin/users \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "email": "budi@example.com",
  "name": "Budi Santoso",
  "password": "correct-horse-battery",
  "balance_nano": 5000000000
}'

Example Request Body

{
  "email": "budi@example.com",
  "name": "Budi Santoso",
  "password": "correct-horse-battery",
  "balance_nano": 5000000000
}

json

application/json

Example Responses

{
  "id": "7c0e1d9a-2b3f-4e5a-8c6d-1f2e3a4b5c6d",
  "email": "budi@example.com",
  "name": "Budi Santoso",
  "is_admin": false,
  "is_owner": false,
  "balance_nano": 12500000000,
  "disabled_at": null,
  "disabled_reason": null,
  "last_login_at": "2026-11-06T09:30:00Z",
  "mfa_enabled": false,
  "email_verified": true,
  "created_at": "2026-03-14T02:11:09Z"
}

json

application/json

Get a user

GET

https://ai.brandkamu.id/api/admin

/users/{id}

Profile, usage statistics (all time and last 30 days), daily usage for the last 30 days (in the site time zone) and the top 10 models of the last 30 days.

Get a user › path Parameters

id

string · uuid · required

User id.

Get a user › Responses

The user's detail.

UserDetail

object · required

object[] · required

Last 30 days in the site time zone; only days with requests.

object[] · required

Top 10 models of the last 30 days by cost.

GET/users/{id}

curl https://ai.brandkamu.id/api/admin/users/:id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "user": {
    "id": "7c0e1d9a-2b3f-4e5a-8c6d-1f2e3a4b5c6d",
    "email": "budi@example.com",
    "name": "Budi Santoso",
    "is_admin": false,
    "is_owner": false,
    "balance_nano": 12500000000,
    "disabled_at": null,
    "disabled_reason": null,
    "last_login_at": "2026-11-06T09:30:00Z",
    "mfa_enabled": false,
    "email_verified": true,
    "created_at": "2026-03-14T02:11:09Z"
  },
  "stats": {
    "requests": 0,
    "errors": 0,
    "tokens": 0,
    "spend_nano": 0,
    "requests_30d": 0,
    "spend_30d_nano": 0,
    "last_request_at": "2024-08-25T15:00:00Z",
    "active_keys": 0,
    "revoked_keys": 0,
    "topups_completed": 0,
    "topped_up_idr": 0,
    "topped_up_nano": 0
  },
  "daily": [
    {
      "day": "2024-08-25",
      "requests": 0,
      "tokens": 0,
      "cost_nano": 0
    }
  ],
  "models": [
    {
      "model_slug": "model_slug",
      "requests": 0,
      "tokens": 0,
      "cost_nano": 0
    }
  ]
}

json

application/json

Update a user

PUT

https://ai.brandkamu.id/api/admin

/users/{id}

Edits a user; omitted fields are unchanged. Setting a password ends the user's other sessions and sends a "password changed" email. The admin role can't be changed (403 if is_admin differs from the current value).

Update a user › path Parameters

id

string · uuid · required

User id.

Update a user › Request Body

email

string · email

name

string

password

string

New password; at least 8 characters (10 for an admin).

is_admin

boolean

Can't change; only accepted when equal to the current value.

email_verified

boolean

true marks the email verified (keeps the original time if already verified); false un-verifies it.

Update a user › Responses

The updated user.

User

id

string · uuid · required

email

string · required

name

string · required

is_admin

boolean · required

is_owner

boolean · required

The initial admin; can't lose the admin role or be suspended.

balance_nano

integer · int64 · required

Balance in nano-USD (1 USD = 1_000_000_000); can be negative.

disabled_at

string | null · date-time · required

Set while the account is suspended.

disabled_reason

string | null · required

last_login_at

string | null · date-time · required

mfa_enabled

boolean · required

email_verified

boolean · required

created_at

string · date-time · required

PUT/users/{id}

curl https://ai.brandkamu.id/api/admin/users/:id \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Budi S.",
  "email_verified": true
}'

Example Request Body

{
  "name": "Budi S.",
  "email_verified": true
}

json

application/json

Example Responses

{
  "id": "7c0e1d9a-2b3f-4e5a-8c6d-1f2e3a4b5c6d",
  "email": "budi@example.com",
  "name": "Budi Santoso",
  "is_admin": false,
  "is_owner": false,
  "balance_nano": 12500000000,
  "disabled_at": null,
  "disabled_reason": null,
  "last_login_at": "2026-11-06T09:30:00Z",
  "mfa_enabled": false,
  "email_verified": true,
  "created_at": "2026-03-14T02:11:09Z"
}

json

application/json

Suspend or unsuspend a user

POST

https://ai.brandkamu.id/api/admin

/users/{id}/status

{"disabled": true} suspends the account: the user is signed out, can't sign in, and their API keys stop working at once (cached authentications are cleared). Nothing is deleted. {"disabled": false} restores access and clears the reason.

The initial admin can't be suspended (403), you can't suspend yourself (400), and at least one enabled admin must remain (400).

Suspend or unsuspend a user › path Parameters

id

string · uuid · required

User id.

Suspend or unsuspend a user › Request Body

disabled

boolean · required

true suspends, false unsuspends.

reason

string | null · maxLength: 500

Optional, shown to admins; trimmed and cut to 500 characters. Ignored when unsuspending.

Suspend or unsuspend a user › Responses

The user with the new status.

User

id

string · uuid · required

email

string · required

name

string · required

is_admin

boolean · required

is_owner

boolean · required

The initial admin; can't lose the admin role or be suspended.

balance_nano

integer · int64 · required

Balance in nano-USD (1 USD = 1_000_000_000); can be negative.

disabled_at

string | null · date-time · required

Set while the account is suspended.

disabled_reason

string | null · required

last_login_at

string | null · date-time · required

mfa_enabled

boolean · required

email_verified

boolean · required

created_at

string · date-time · required

POST/users/{id}/status

curl https://ai.brandkamu.id/api/admin/users/:id/status \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "disabled": true,
  "reason": "Chargeback on top-up order 20260101-ABC"
}'

Example Request Body

{
  "disabled": true,
  "reason": "Chargeback on top-up order 20260101-ABC"
}

json

application/json

Example Responses

{
  "id": "7c0e1d9a-2b3f-4e5a-8c6d-1f2e3a4b5c6d",
  "email": "budi@example.com",
  "name": "Budi Santoso",
  "is_admin": false,
  "is_owner": false,
  "balance_nano": 12500000000,
  "disabled_at": null,
  "disabled_reason": null,
  "last_login_at": "2026-11-06T09:30:00Z",
  "mfa_enabled": false,
  "email_verified": true,
  "created_at": "2026-03-14T02:11:09Z"
}

json

application/json

Resend the verification email

POST

https://ai.brandkamu.id/api/admin

/users/{id}/verification-email

Sends the user a new email-verification link. 400 if the email is already verified or SMTP isn't set up.

Resend the verification email › path Parameters

id

string · uuid · required

User id.

Resend the verification email › Responses

Sent.

sent

boolean · const · required

Const value:

Add or deduct credit

POST

https://ai.brandkamu.id/api/admin

/users/{id}/credit

Changes the user's balance by delta_nano (positive grants, negative deducts; the balance may go below zero). Recorded in the audit log and the user's balance history.

Add or deduct credit › path Parameters

id

string · uuid · required

User id.

Add or deduct credit › Request Body

delta_nano

integer · int64 · required

Signed amount in nano-USD (1 USD = 1_000_000_000). Can't be zero.

note

string | null · maxLength: 200

Shown in the balance history (e.g. "refund"); trimmed and cut to 200 characters.

Add or deduct credit › Responses

The new balance.

balance_nano

integer · int64 · required

New balance in nano-USD.

Reset two-factor authentication

POST

https://ai.brandkamu.id/api/admin

/users/{id}/mfa/reset

Turns the user's 2FA off (e.g. lost phone and recovery codes), ends their sessions and emails them. An admin is asked to set 2FA up again at their next sign-in. 400 if 2FA isn't on.

Reset two-factor authentication › path Parameters

id

string · uuid · required

User id.

Reset two-factor authentication › Responses

2FA is off.

mfa_enabled

boolean · required

List a user's top-ups

GET

https://ai.brandkamu.id/api/admin

/users/{id}/topups

The user's top-up requests in every status, newest first.

List a user's top-ups › path Parameters

id

string · uuid · required

User id.

List a user's top-ups › query Parameters

limit

integer · min: 1 · max: 200

Page size (clamped to 1-200).

Default: 20

offset

integer · min: 0

Rows to skip.

Default: 0

List a user's top-ups › Responses

A page of top-ups.

UserTopup[] · required

total

integer · required

Get a user's balance history

GET

https://ai.brandkamu.id/api/admin

/users/{id}/balance-history

Every change to the balance, newest first: paid top-ups, coupon redemptions, affiliate rewards, admin credit and starting balance (from the audit log), and usage as one row per day.

Get a user's balance history › path Parameters

id

string · uuid · required

User id.

Get a user's balance history › query Parameters

limit

integer · min: 1 · max: 200

Page size (clamped to 1-200).

Default: 20

offset

integer · min: 0

Rows to skip.

Default: 0

Get a user's balance history › Responses

A page of balance changes.

BalanceEntry[] · required

total

integer · required

List a user's API keys

GET

https://ai.brandkamu.id/api/admin

/users/{id}/keys

All of the user's API keys, revoked ones included (active first, then newest; at most 200). Secrets are never returned.

List a user's API keys › path Parameters

id

string · uuid · required

User id.

List a user's API keys › Responses

The keys (not paginated).

UserKey[]

UserKey

id

string · uuid · required

name

string · required

key_prefix

string · required

Masked display form, e.g. sk-****-a1b2.

credit_limit_nano

integer | null · int64 · required

Spending limit in nano-USD; null for none.

usage_nano

integer · int64 · required

Spend so far, nano-USD.

allowed_models

array | null · required

expires_at

string | null · date-time · required

allowed_ips

array | null · required

redact_secrets

boolean · required

last_used_at

string | null · date-time · required

revoked_at

string | null · date-time · required

created_at

string · date-time · required

List a user's recent requests

GET

https://ai.brandkamu.id/api/admin

/users/{id}/requests

The user's AI requests, newest first (metadata only). Use GET /logs?user= for filters.

List a user's recent requests › path Parameters

id

string · uuid · required

User id.

List a user's recent requests › query Parameters

limit

integer · min: 1 · max: 200

Page size (clamped to 1-200).

Default: 20

offset

integer · min: 0

Rows to skip.

Default: 0

List a user's recent requests › Responses

A page of requests.

UserRequest[] · required

total

integer · required

List a user's activity

GET

https://ai.brandkamu.id/api/admin

/users/{id}/activity

The user's audit timeline, newest first: what they did (sign-ins, keys, top-ups) and what was done to their account (credit, suspension, edits).

List a user's activity › path Parameters

id

string · uuid · required

User id.

List a user's activity › query Parameters

limit

integer · min: 1 · max: 200

Default: 30

offset

integer · min: 0

Rows to skip.

Default: 0

List a user's activity › Responses

A page of audit entries.

AuditEntry[] · required

total

integer · required

GET/users/{id}/activity

curl https://ai.brandkamu.id/api/admin/users/:id/activity \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "items": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "actor_id": "9f8e7d6c-5b4a-4321-8fed-cba987654321",
      "actor_email": "admin@brandkamu.id",
      "action": "admin user.credit",
      "target_type": "user",
      "target_id": "7c0e1d9a-2b3f-4e5a-8c6d-1f2e3a4b5c6d",
      "details": {
        "delta_nano": 10000000000,
        "balance_nano": 12500000000,
        "note": "Refund",
        "admin_api_key": "0b9a7c52-8e7d-4d3a-9c1e-4f6a2b8d0e11"
      },
      "ip": "203.0.113.7",
      "created_at": "2026-11-06T10:15:00Z"
    }
  ],
  "total": 0
}

json

application/json

Virtual keys