Authentication

Authenticate with the Earnipay API to get access tokens for making API requests. This page covers the full authentication flow: registering an account, verifying your email, logging in, and managing tokens.

Auth Methods

The Earnipay API supports two authentication methods:

Method	Header	Use Case
JWT Bearer Token	`Authorization: Bearer <token>`	User-facing flows — login to get an access token and refresh token
API Key	`X-API-Key: <key>`	Third-party integrations — pass your key with every request

Endpoints

Method	Endpoint	Description
POST	`/v1/auth/signup`	Register a new user account
POST	`/v1/auth/verify-email`	Verify email with a 6-digit code
POST	`/v1/auth/resend-code`	Resend the verification code
POST	`/v1/auth/login`	Log in with email and password
POST	`/v1/auth/refresh`	Refresh an expired access token
POST	`/v1/auth/logout`	Invalidate a refresh token
POST	`/v1/auth/forgot-password`	Request a password reset link
POST	`/v1/auth/reset-password`	Reset password with a token

Registration Flow

1. Sign Up

Create a new user account with your email and password.

curl -X POST https://e-invoicing.earnipay.com/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "min8characters",
    "firstName": "Ada",
    "lastName": "Okafor"
  }'

Parameter	Type	Required	Description
`email`	string	Yes	Your email address
`password`	string	Yes	Minimum 8 characters
`firstName`	string	No	Your first name
`lastName`	string	No	Your last name

{
  "statusCode": 201,
  "message": "Account created successfully. Please verify your email.",
  "data": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "firstName": "Ada",
    "lastName": "Okafor",
    "isEmailVerified": false
  }
}

2. Verify Email

Enter the 6-digit verification code sent to your email to activate your account.

curl -X POST https://e-invoicing.earnipay.com/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "code": "482901"
  }'

Parameter	Type	Required	Description
`email`	string	Yes	The email address you registered with
`code`	string	Yes	6-digit verification code from your email

{
  "statusCode": 200,
  "message": "Email verified successfully."
}

3. Resend Verification Code

Request a new code if the original expired or didn't arrive.

curl -X POST https://e-invoicing.earnipay.com/v1/auth/resend-code \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

{
  "statusCode": 200,
  "message": "Verification code resent successfully."
}

Login

Exchange your email and password for an access token and refresh token.

curl -X POST https://e-invoicing.earnipay.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "min8characters"
  }'

Parameter	Type	Required	Description
`email`	string	Yes	Your registered email address
`password`	string	Yes	Your account password

{
  "statusCode": 200,
  "message": "Login successful.",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "firstName": "Ada",
      "lastName": "Okafor",
      "isEmailVerified": true
    }
  }
}

Use the accessToken in the Authorization header for all subsequent API calls:

curl https://e-invoicing.earnipay.com/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

⏱️
Access tokens expire after a set period. Store the refreshToken securely — you'll need it to get a new access token without logging in again.

Token Management

Refresh Access Token

Exchange an expired access token for a new one using your refresh token.

curl -X POST https://e-invoicing.earnipay.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Parameter	Type	Required	Description
`refreshToken`	string	Yes	The refresh token from your last login or refresh

{
  "statusCode": 200,
  "message": "Token refreshed successfully.",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Logout

Invalidate your refresh token. The access token remains valid until it expires, but no new tokens can be issued from the invalidated refresh token.

curl -X POST https://e-invoicing.earnipay.com/v1/auth/logout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

{
  "statusCode": 200,
  "message": "Logged out successfully."
}

Password Reset

1. Request Reset Link

Send a password reset link to your registered email.

curl -X POST https://e-invoicing.earnipay.com/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

{
  "statusCode": 200,
  "message": "Password reset link sent to your email."
}

2. Reset Password

Use the token from the reset email to set a new password.

curl -X POST https://e-invoicing.earnipay.com/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "password": "newSecurePassword123"
  }'

Parameter	Type	Required	Description
`token`	string	Yes	Reset token from the email link
`password`	string	Yes	New password (minimum 8 characters)

{
  "statusCode": 200,
  "message": "Password reset successfully."
}

Error Handling

Authentication endpoints return standard error responses. Handle these in your integration:

Status Code	Error	Description
`400`	Bad Request	Missing or invalid parameters (e.g., password too short)
`401`	Unauthorized	Invalid credentials, expired token, or invalid refresh token
`404`	Not Found	Email address not registered
`409`	Conflict	Email address already registered
`429`	Too Many Requests	Rate limit exceeded — wait before retrying

{
  "statusCode": 401,
  "message": "Invalid email or password.",
  "error": "Unauthorized"
}

Token refresh flow for SDKs and clients

Implement automatic token refresh to avoid interrupting your users:

Make an API request with your current access token
If you receive a 401 response, call POST /v1/auth/refresh with your stored refresh token
If the refresh succeeds, retry the original request with the new access token
If the refresh fails (refresh token also expired), redirect the user to log in again

async function apiRequest(url, options = {}) {
  let response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${getAccessToken()}`,
    },
  });

  // Access token expired — try refreshing
  if (response.status === 401) {
    const refreshResponse = await fetch(
      'https://e-invoicing.earnipay.com/v1/auth/refresh',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ refreshToken: getRefreshToken() }),
      }
    );

    if (refreshResponse.ok) {
      const { data } = await refreshResponse.json();
      saveTokens(data.accessToken, data.refreshToken);

      // Retry the original request with the new token
      response = await fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          'Authorization': `Bearer ${data.accessToken}`,
        },
      });
    } else {
      // Refresh token also expired — user must log in again
      redirectToLogin();
    }
  }

  return response;
}