Authentication

The Ping API supports two authentication methods: JWT tokens for user-facing dashboard applications and API keys for server-to-server integrations. Choose the method that best fits your use case.

Authentication methods

JWT Tokens (Dashboard/User Auth)

Use JWT (JSON Web Tokens) for:

User login flows in web/mobile apps
Dashboard applications
Admin panels
Agent interfaces

JWT tokens are obtained via the login endpoint and must be refreshed periodically.

API Keys (Server-to-Server)

Use API keys for:

Backend service integrations
Automated notification systems
Cron jobs and scheduled tasks
Third-party application integrations

API keys are long-lived credentials managed in your dashboard.

Security Best Practice: Never expose API keys in client-side code (browsers, mobile apps). Use JWT authentication for client-facing applications.

JWTUser/Dashboard Access

JWT authentication

JWT authentication is used for user-facing applications. Obtain tokens via the login endpoint and include them in subsequent requests.

Login

Authenticate a user and receive access and refresh tokens.

Required headers

Name
User-Type
Type
string
Description
Type of user authenticating: user, adminuser, or agent.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
email
Type
string
Description
User's email address.
Name
password
Type
string
Description
User's password.

Request

POST

/v1/auth/login

curl -X POST https://api.ping.co.zw/v1/auth/login \
  -H "User-Type: user" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }'

Response

{
  "result": "success",
  "message": "You have successfully logged in!",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "public_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "John",
    "last_name": "Doe",
    "email_address": "[email protected]",
    "phone_number": "+263771234567"
  },
  "businesses": [
    {
      "id": 1,
      "public_id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp",
      "status": "verified"
    }
  ]
}

POST/v1/auth/refresh

Refresh token

Access tokens expire after 30 days. 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.
Name
userType
Type
string
Description
Type of user: user, adminuser, or agent.

Request

POST

/v1/auth/refresh

curl -X POST https://api.ping.co.zw/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userType": "user"
  }'

Response

{
  "result": "success",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using JWT tokens

Include the access token in the Authorization header for all authenticated requests.

JWT token structure

Tokens contain:

public_id - User's unique identifier
session_id - Session identifier
iat - Issued at timestamp
exp - Expiration timestamp

Token expiration

Access tokens: 30 days
Refresh tokens: 180 days

After expiration, use the refresh token to obtain a new access token.

Using JWT in requests

curl https://api.ping.co.zw/v1/get/businesses \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "User-Type: user"

Required headers with JWT:

Authorization: Bearer <accessToken>
User-Type: user | adminuser | agent
X-Business-Id: <id> (for business-scoped requests)

API-KEYServer-to-Server

API key authentication

API keys are used for server-to-server integrations. Create and manage API keys in your Ping dashboard.

API key formats

Test keys: pk_test_* or sk_test_*
Live keys: pk_live_* or sk_live_*

Test keys are for development and don't send real notifications. Live keys are for production use.

Permissions

Each API key has granular permissions:

sms - Send SMS notifications
email - Send email notifications
whatsapp - Send WhatsApp messages
templates - Manage notification templates
bulk - Send bulk notifications

Using API keys

curl -X POST https://api.ping.co.zw/v1/notification/api/sms/send \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone": "+263771234567",
    "message": "Your OTP is 123456"
  }'

Optional header: X-Ping-Required-Permission can specify the required permission (e.g., sms, email) to validate the key has the necessary access.

Comparison

When to use each method

Use Case	Method	Why
Web/mobile app user login	JWT	Supports user sessions, can be refreshed, secure for client apps
Admin dashboard	JWT	User-specific permissions, session management
Backend service (cron jobs)	API Key	No user context needed, long-lived, simpler
Third-party integrations	API Key	No user login flow, service-to-service auth
Automated notifications	API Key	Server-side only, no user interaction

Security considerations

JWT Tokens:

✅ Short-lived (30 days)
✅ User-specific permissions
✅ Can be revoked via logout
⚠️ Requires refresh flow

API Keys:

✅ Long-lived (until revoked)
✅ Granular permissions
✅ No expiration handling needed
⚠️ Must be kept secret (server-side only)

Never expose API keys in:

Client-side JavaScript
Mobile app source code
Public repositories
Browser localStorage/cookies

API keys should only be used in secure server environments.