Authentication and Fundamentals

This page covers the conventions shared by the ISPbills REST APIs. Use the API v1 reference or API v2 reference after obtaining a token.

Request conventions

Base URL:

https://app.ispbills.com/api

Send JSON and explicitly request JSON responses:

Accept: application/json
Content-Type: application/json

Protected endpoints also require:

Authorization: Bearer YOUR_TOKEN

API v1 authentication

API v1 authenticates an active operator by email or mobile number. The username field accepts either value.

POST /api/v1/auth/login
Accept: application/json
Content-Type: application/json

{
  "username": "[email protected]",
  "password": "your-password"
}

A successful response returns a token, a refresh token, and operator details:

{
  "token": "60-character-access-token",
  "refresh_token": "60-character-refresh-token",
  "user": {
    "id": 42,
    "name": "Example Operator",
    "email": "[email protected]",
    "role": "group_admin",
    "permissions": []
  }
}

Use token as the bearer token. To rotate both tokens without sending the password again:

POST /api/v1/auth/refresh
Accept: application/json
Content-Type: application/json

{
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

Social authentication is available to the official client at POST /api/v1/auth/social. It accepts provider (google or facebook) and the provider-issued id_token.

API v2 client credentials

Create an API v2 client under Integrations → API Management. Copy the Client ID and Client Secret when they are displayed.

Exchange them for a bearer token:

POST /api/v2/auth/token
Accept: application/json
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

The response contains the active token and granted scopes:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "scopes": ["customers:read", "customers:write", "sms:send"]
}

Use the token on protected v2 requests:

GET /api/v2/customers
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Revoke the current token when it is no longer needed:

POST /api/v2/auth/revoke
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Revocation takes effect immediately. Exchange the client credentials again to obtain another token.

API v2 scopes

API clients carry a list of scopes. The customer and SMS controllers currently enforce these scopes directly:

Scope	Access
customers:read	Customer list/detail plus customer bills, payments, subscriptions, and usage
customers:write	Create, update, and delete customers
sms:send	Send individual and broadcast SMS messages
*	Full access; grant only to tightly controlled integrations

The API Management screen also exposes scopes for billing, payments, packages, reports, and other integrations. Assign the smallest set required by the client.

Pagination

Collection endpoints generally accept:

Query parameter	Meaning
page	Page number, starting at 1
per_page	Records per page; most endpoints cap this at 100

Paginated API v2 responses use this envelope:

{
  "data": [],
  "total": 0,
  "page": 1,
  "last_page": 0
}

Some API v1 collections also accept resource-specific filters such as search and status.

Success and error responses

Successful resource responses normally contain data. Delete and revoke operations return a message. API v1 legacy endpoints may return a resource directly.

Common failures are:

Status	Meaning	Typical response field
401	Missing, invalid, or revoked token	error or message
403	Account disabled or scope/permission denied	error or message
404	Resource not found within the authenticated operator	error or message
422	Request validation failed	message and errors
429	Client or endpoint rate limit exceeded	error and sometimes retry_after
500	Unexpected server failure	message

Laravel validation responses include field-level details:

{
  "message": "The given data was invalid.",
  "errors": {
    "mobile": ["The mobile field is required."]
  }
}

Do not rely on a single error envelope across every v1 legacy endpoint. Check the HTTP status first, then inspect error, message, and errors.

Rate limits

API v2 limits are configured per API client. A v2 limit response includes the remaining seconds in the current minute window:

{
  "error": "Too Many Requests",
  "retry_after": 27
}

Wait at least retry_after seconds, then retry with exponential backoff and jitter. API v1 and public authentication routes may have separate route-level limits.

Integration checklist

• Set connect and response timeouts.
• Retry only safe reads or idempotent operations unless your workflow has its own idempotency key.
• Keep operator data isolated; the API scopes records to the authenticated operator or API client.
• Log the route, status, and a local correlation ID, but never log credentials.
• Rotate credentials immediately if they may have been exposed.