Weaf MRA EIS Api

Malawi Revenue Authority EIS Integration

🚀

Authentication

Secure token-based authentication system for API access. Generate, validate, and manage access tokens with customizable expiration periods.

StepWhat to do
1. GeneratePOST your account email (username) and password with expiry_days (1 to 365) and a descriptive token_name. Pass tin to restrict the token to one company.
2. UseSend the token as the token query parameter and as Authorization: Bearer {token} on every MRA call.
3. CheckValidate a token to confirm it's still active and see which user and companies it covers.
4. RefreshBefore expiry, refresh with the current token as the Bearer header. You get a new token and the old one is invalidated.

🔐 Token handling

  • Keep tokens server-side. Never ship them in browser or mobile app bundles.
  • A token has the same rights as your account for its companies. Use one token per integration so you can revoke them independently.
  • Around 30 days is a sensible expiry. Schedule the refresh rather than waiting for a 401.

Endpoints in this section

Generate API Access Token

🚀 Try it
POST/api/v1/auth/generate-token

Authenticate a user and generate an API access token for programmatic access to the system. This endpoint validates user credentials and creates a secure token that can be used for subsequent API calls. The token provides access to company-specific data and operations based on the user's permissions.

Request Body

User credentials and token configuration parameters

FieldTypeRequiredDescription
usernamestring (email)Yes

User's email address used for authentication. Must be a valid email format and correspond to an existing user account in the system.

Example: user@example.com
passwordstringYes

User's account password. Must be at least 6 characters long and match the user's stored password hash.

Example: SecurePassword123!
expiry_daysintegerYes

Number of days until the token expires. Must be between 1 and 365 days. Recommended: 30 days for optimal security. Longer periods increase security risk.

min 1 · max 365

 Example: 30
token_namestringYes

Human-readable name for the token to help identify its purpose, usage, or associated application. Maximum 255 characters. Useful for token management and security auditing.

max length 255

 Example: Mobile App Integration
tinstringNo

Optional TIN to restrict the token to a single company. If not provided, the token will have access to all companies associated with the user.

max length 20 · nullable

Responses

  • 200Token generated successfully - Authentication successful
  • 400Validation Error - Invalid request data
  • 401Authentication Failed - Invalid credentials
  • 403Access Forbidden - User account restrictions
  • 500Internal Server Error - System error occurred

Validate access token

🚀 Try it
POST/api/v1/auth/validate-token

Validate an existing access token and get user/company information

Request Body

FieldTypeRequiredDescription
tokenstringYes

64-character access token

max length 64

 Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4

Responses

  • 200Token is valid
  • 400Validation error
  • 401Invalid or expired token
  • 500Internal server error

Refresh API Access Token

🚀 Try it
POST/api/v1/auth/refresh-token🔒 token required

Refresh an existing access token to get a new token with extended expiration period. This endpoint allows you to extend the validity of your current token without re-authenticating with username and password. The new token will have a longer expiration period and the old token will be invalidated.

Important for Swagger UI users:

  1. First, add your current token to the Bearer token field using the 'Authorize' button above
  2. Then use this endpoint to refresh your token
  3. The old token will be passed in both the request body AND the Authorization header

Request Body

Token refresh parameters

FieldTypeRequiredDescription
expiry_daysintegerYes

Number of days until the new token expires. Must be between 1 and 365 days. Recommended: 60-90 days for refreshed tokens.

min 1 · max 365

 Example: 60
token_namestringYes

New descriptive name for the refreshed token. Maximum 255 characters. This helps identify the refreshed token in your token management.

max length 255

 Example: Refreshed Mobile App Token

Responses

  • 200Token refreshed successfully
  • 400Validation Error - Invalid request data
  • 401Authentication Failed - Invalid or expired token
  • 403Access Forbidden - Token refresh not allowed
  • 500Internal Server Error - System error occurred