Quickstart

This guide walks you through the four steps needed to start using the ZB ID API: registering a user, logging in to receive tokens, making an authenticated request, and refreshing your access token when it expires.

These docs are interactive. Look for the "Try it" panels throughout, they run live against the ZB ID staging sandbox (id-staging.zb.co.zw). Register a throwaway account and sign in on the Authentication page, and your token carries across the token-scoped panels.

POST/auth/register

Register a user

Create a new user account by providing at least one login channel (a phone number, an email, or both) and a password. First and last name are optional. A phone number must match ^\+?[0-9]{10,15}$ (for example, +263771234567).

Attributes

Name
email
Type
string
Description
The user's email address. Supply this or phone (or both).
Name
phone
Type
string
Description
The user's phone number. Supply this or email (or both).
Name
password
Type
string
Description
A strong password for the account. Between 8 and 128 characters.
Name
firstName
Type
string
Description
Optional. The user's first name.
Name
lastName
Type
string
Description
Optional. The user's last name.

Request

POST

/auth/register

curl -X POST https://id.zb.co.zw/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+263771234567",
    "password": "secureP@ss1",
    "firstName": "Tatenda",
    "lastName": "Moyo",
    "email": "[email protected]"
  }'

Response (201)

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "sT9kQ2mVr8...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "phone": "+263771234567",
    "email": "[email protected]",
    "firstName": "Tatenda",
    "lastName": "Moyo",
    "kycTier": "NONE",
    "roles": ["customer"]
  }
}

POST/auth/login

Log in

Authenticate with either the email or the phone number you registered, plus your password. Email is case-insensitive. On success, the API returns an access token and a refresh token. Store both tokens securely; you will need the access token for every authenticated request and the refresh token to obtain new access tokens.

Required attributes

Name
phone
Type
string
Description
The phone used during registration. Supply this or email.
Name
email
Type
string
Description
The email used during registration. Supply this or phone.
Name
password
Type
string
Description
The account password.

Request

POST

/auth/login

curl -X POST https://id.zb.co.zw/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+263771234567",
    "password": "secureP@ss1"
  }'

Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "sT9kQ2mVr8...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "phone": "+263771234567",
    "email": "[email protected]",
    "firstName": "Tatenda",
    "lastName": "Moyo",
    "kycTier": "NONE",
    "roles": ["customer"]
  }
}

GET/users/me

Use your token

With your access token in hand, you can call any authenticated endpoint. Include the token in the Authorization header as a Bearer token. The /users/me endpoint returns the profile of the currently authenticated user, which makes it a good first test.

Required headers

Name
Authorization
Type
string
Description
Must be Bearer <accessToken> where <accessToken> is the token returned from the login endpoint.

Request

GET

/users/me

curl https://id.zb.co.zw/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "phone": "+263771234567",
  "email": "[email protected]",
  "firstName": "Tatenda",
  "lastName": "Moyo",
  "kycTier": "NONE",
  "status": "ACTIVE",
  "roles": [
    {
      "id": "a0000000-0000-0000-0000-000000000001",
      "name": "customer",
      "description": "Standard retail customer",
      "subsidiaryScope": null
    }
  ],
  "createdAt": "2026-07-10T10:00:00Z",
  "emailVerifiedAt": null,
  "phoneVerifiedAt": null
}

POST/auth/token/refresh

Refresh your token

Access tokens expire after a set period. When that happens, use the refresh token to obtain a new access token without requiring the user to log in again.

Required attributes

Name
refreshToken
Type
string
Description
The refresh token received during login or from a previous refresh call.

ZB ID uses refresh token rotation. Each time you refresh, the API issues both a new access token and a new refresh token. The old refresh token is immediately invalidated. If a previously used refresh token is submitted again, all tokens for that user session are revoked as a security measure (replay detection). Always store and use the latest refresh token.

Request

POST

/auth/token/refresh

curl -X POST https://id.zb.co.zw/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }'

Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "b4Xr7pW1nZ...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "phone": "+263771234567",
    "email": "[email protected]",
    "firstName": "Tatenda",
    "lastName": "Moyo",
    "kycTier": "NONE",
    "roles": ["customer"]
  }
}