Authentication

Eclipse uses JWT (JSON Web Token) based authentication. Users authenticate with their identity (username) and password to receive a JWT token that must be included in all subsequent API requests.

Authentication Flow

1. Initial Login - Request JWT Token

Endpoint:

POST {baseUrl}/eclipse-conductor/rest/v1/authentication/login

Request Headers:

Content-Type: application/json

Request Body:

{
  "identity": "username",
  "password": "user_password"
}

Successful Response (200 OK):

{
  "headerName": "Authorization",
  "headerValue": "Bearer 24634...",
  "sessionId": "abc123-session-id",
  "roles": ["GLOBAL_ADMIN"],
  "csrfHeaderName": "renew-csrf",
  "csrfToken": "352435",
  "expiresEpochSecs": 1774277221
}

The JWT is returned in the headerValue field after the key word Bearer.

Failed Response (401 Unauthorized):

[
    {
        "type": "BUSINESS",
        "severity": "LOW",
        "description": "Incorrect identity/password",
        "code": "USR002",
        "traceId": "2d4c74754749c038fdb4149ae6100219",
        "spanId": "71b4672cbf575634",
        "environment": "eclipse-java-sandbox"
    }
]

2. Using the JWT Token

All authenticated API requests must include the JWT token in the Authorization header.

The customerId for the customer can be retrieved from the JWT - it is the uid field encoded in the JWT.

Header Format:

Authorization: Bearer {jwt_token}

Example Authenticated Request:

const response = await fetch(
  `https://{baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${jwtToken}`,
      "Content-Type": "application/json",
    },
  }
);

4. JWT Token Renewal

JWT tokens expire after a configurable period (typically 1 hour). Before expiration, use the renew endpoint to obtain a new JWT without requiring the user to re-enter credentials.

Endpoint:

POST {baseUrl}/eclipse-conductor/rest/v1/authentication/renew

Request Headers:

Content-Type: application/json
Authorization: Bearer {current_jwt_token}

Request Body:

{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Successful Refresh Response (200 OK):

{
  "headerName": "Authorization",
  "headerValue": "Bearer 24634...",
  "sessionId": "abc123-session-id",
  "roles": ["GLOBAL_ADMIN"],
  "csrfHeaderName": "renew-csrf",
  "csrfToken": "352435",
  "expiresEpochSecs": 1774277221
}

6. Logout

Endpoint:

POST {baseUrl}/eclipse-conductor/rest/v1/authentication/logout

Request Headers:

Content-Type: application/json
Authorization: Bearer {jwt_token}

Request Body:

{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

7. Initiate Password Change (OTP)

Request an OTP:

This API initiates a password change by sending a One-Time PIN (OTP) to the phone number associated with the user’s identity. Only the identity (username) is required. No JWT is required for this request.

Endpoint:

POST {baseUrl}/eclipse-conductor/rest/v1/global/identities/{identity}/password-change-init
{
  "type": "OTP"
}

This will trigger an SMS containing the OTP to the customer’s registered phone number on their Eclipse profile.

Update Password

This API completes the password change using the OTP received.

Endpoint:

POST {baseUrl}/eclipse-conductor/rest/v1/global/identities/{identity}/password-change
{
  "hash": "otp_received_via_sms",
  "password": "new_password"
}

8. Security Best Practices

1. Store tokens securely: Use localStorage for web apps, secure storage for mobile
2. Never expose tokens in URLs: Always use Authorization header
3. Implement token refresh: Proactively refresh tokens before expiration, check token expiry before sending any requests
4. Handle logout properly: Clear all stored tokens and call logout endpoint
5. Validate tokens client-side: Check expiration before making requests
6. Use HTTPS only: Never transmit tokens over unencrypted connections
7. Implement timeout: Auto-logout users after period of inactivity