Skip to main content

Authentication

SkyPay uses different authentication methods depending on the context:

  • User Authentication (JWT): For actions performed by logged-in users within the Merchant or Admin portals, SkyPay uses JSON Web Tokens (JWT). Obtain a token via the Login endpoint and include it in the Authorization header as a Bearer token (Authorization: Bearer YOUR_JWT_TOKEN) for protected endpoints.
  • API Key Authentication: For direct server-to-server API calls (like initiating payments from your backend), you will use your SkyPay API keys (Test or Live Secret Key). These should be sent in the Authorization header as a Bearer token (Authorization: Bearer YOUR_SECRET_KEY). (Note: API Key authentication middleware is not yet implemented in the example backend).
  • Webhook Signature Verification: To secure webhook endpoints, SkyPay relies on signature verification using secrets shared between SkyPay and your application. See the Webhooks documentation for details.

Sign Up​

Creates a new merchant account and the initial owner user.

POST /api/auth/signup (Public)

Request Body​

{
  "firstName": "Test",
  "lastName": "User",
  "email": "test@example.com",
  "password": "password123",
  "businessName": "Test Business Ltd."
}

Response 201 Created​

Returns the created user (excluding sensitive fields) and merchant details. Sends a verification email.

{
  "message": "Merchant registration successful",
  "user": {
    "id": "uuid-user-123",
    "firstName": "Test",
    "lastName": "User",
    "email": "test@example.com",
    "role": "merchant_owner",
    "isEmailVerified": false,
    "createdAt": "...",
    "updatedAt": "...",
    "ownedMerchant": { /* Partial merchant details */ }
  },
  "merchant": {
    "id": "uuid-merchant-456",
    "businessName": "Test Business Ltd.",
    "status": "pending",
    "environment": "test",
    "testApiKey": "sk_test_...",
    "testSecretKey": "sk_test_sec_...",
    "createdAt": "...",
    "updatedAt": "...",
    "owner": { /* Partial user details */ }
  }
}

Errors​

  • 400 Bad Request: Validation failed.
  • 409 Conflict: User with this email already exists.
  • 500 Internal Server Error

Login​

Authenticates a user and returns a JWT.

POST /api/auth/login (Public)

Request Body​

{
  "email": "test@example.com",
  "password": "password123"
}

Response 200 OK​

Returns a JWT and user details (excluding sensitive fields).

{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid-user-123",
    "firstName": "Test",
    "lastName": "User",
    "email": "test@example.com",
    "role": "merchant_owner",
    "isEmailVerified": true,
    "createdAt": "...",
    "updatedAt": "...",
    "ownedMerchant": { /* ... */ }
  }
}

Errors​

  • 400 Bad Request: Validation failed.
  • 401 Unauthorized: Invalid credentials or Email not verified.
  • 500 Internal Server Error

Verify Email Address​

Verifies a user's email address using the token sent via email after signup.

GET /api/auth/verify-email (Public - Accessed via link)

Query Parameters​

ParameterTypeDescription
tokenStringThe email verification token.

Response 200 OK​

{
  "message": "Email verified successfully. You can now log in."
}

Errors​

  • 400 Bad Request: Token missing or verification failed (invalid/expired token).
  • 500 Internal Server Error