Profile & workspaces

All endpoints on this page require a JWT:

Authorization: Bearer <access_token>

Choose the operation

Profile

{
  "id": "52cd58a7-8e06-43e7-b8d5-e51d656e0178",
  "full_name": "Emmanuel Lugenge",
  "avatar_url": null,
  "email": "you@example.com",
  "phone_number": "+255628587749",
  "email_verified": true,
  "phone_verified": true,
  "status": "active",
  "role": "user",
  "created_at": "2026-07-14T11:59:52.99Z"
}

Optional fields such as avatar_url, email, and phone_number may be omitted rather than returned as null when they are unset. If your UI needs to distinguish those states, check whether the key exists.

Send only the fields that changed:

{
  "full_name": "New Name",
  "avatar_url": "https://cdn.example.com/me.png"
}

full_name and avatar_url are independent optional fields. When supplied, avatar_url must be a valid URL. A successful response is 200 and returns the updated profile in the same shape as GET /v1/me.

This performs a soft delete and accepts no body. The 200 response is {}. The account becomes unusable and cannot be restored through the API, so expose this action only behind an explicit confirmation step.

Add or change your phone number

The way to attach a (new) phone number to your account — required before a mobile-money top-up is allowed. Sets the number, resets phone_verified to false, and fires a verify_phone OTP to it.

{ "phone_number": "+255712345678" }

phone_number must be E.164 (+ and country code). Response 200:

{ "pending_verification": true }

Complete the verification with the existing POST /v1/auth/otp/verify using {"identifier", "channel": "phone", "purpose": "verify_phone", "code"}. Errors: validation_error (400, malformed number), conflict (409, that phone is already registered to another account).

Workspaces

Ngamia creates a default workspace automatically when the user first logs in or verifies their account. Create additional workspaces when you need separate API keys and usage views—for example, one for Production and one for Staging.

The response is an array, with the default workspace first. A workspace has this shape:

{
  "id": "910e5104-f604-47d4-b194-3db2fbd83f76",
  "name": "Production App",
  "slug": "production-app",
  "description": "my prod app",
  "is_default": false,
  "created_at": "2026-07-14T11:21:34Z",
  "updated_at": "2026-07-14T11:21:45Z"
}

description is omitted when it is unset.

{
  "name": "Production App",
  "slug": "production-app",
  "description": "my prod app"
}

A successful create returns 201 and the new workspace. A bad slug returns validation_error (400); a slug already used by the account returns conflict (409). Each user may create up to 20 additional workspaces; exceeding that limit returns 403 forbidden.

Read, update, or delete a workspace

Update either field independently:

{
  "name": "Production API",
  "description": "Customer-facing production traffic"
}

Send "description": "" to clear the description. A successful update returns 200 with the updated workspace.

A successful delete returns:

{ "status": "deleted" }

The default workspace cannot be deleted and returns validation_error (400). When deleting another workspace, Ngamia first reassigns its API keys to the default workspace. Warn users that the keys move; they are not deleted.

For key creation and workspace assignment, continue with API keys. For usage records, see Activity & analytics.