Implement JWT Token Refresh Mechanism

Problem Statement

When a user's auth token expires, and they relaunch the app, there is no way to silently restore their session. The current refresh endpoint only accepts a non-expired JWT, so once a token has expired, the app hits a dead end. Without a proper token recovery mechanism, users are forced to manually sign in again — creating unnecessary friction and drop-off at relaunch.
Since the auth token is used in every request and is frequently exposed, extending the auth token’s TTL is not a secure resolution for this issue.

User Story

As a returning app user whose auth token has expired since their last session, I want the app to silently restore my session on launch without prompting me to sign in again, so that I can resume using the app immediately with my subscription state loaded, even if it has been last used long ago.

Definition of Done

A user object contains both a short-lived access token that cannot be refreshed and a long-lived refresh token.
The refresh endpoint accepts a non-expired refresh JWT and returns a new short-lived access token along with a new refresh token.
The authentication endpoint accepts a non-expired auth JWT and returns the requested information/performs the requested function.
A refresh_ttl window is defined and enforced — tokens outside this window cannot be refreshed and require re-authentication.
If the auth token is close to expiring, the app uses the stored refresh token to call the refresh endpoint on launch; if successful, the new refresh and auth tokens are stored and the session resumes silently.
If the refresh fails (token outside refresh_ttl or invalid), the app falls back gracefully to the sign-in screen.
Subscription state is successfully queried using the new auth token after a silent refresh.
Changes are documented in the API reference.

Posted by Rana Haleem · Jun 3

Planned2

Rana Haleem

Team•

Sep 17

•

Merged request

•

3 votes

Customer Token Verification: JWKS Endpoint & Token Validation

🔍 Problem Statement

As a developer integrating Pelcro authentication, I have no way to verify a customer's token independently: Pelcro signs with HS256 and cannot share the secret, and there is no endpoint that reports whether an auth.token is valid, expired, or revoked. Every check therefore costs an API round-trip (100–500ms) or an indirect probe with an authenticated request.

💡 User Story

As a developer integrating Pelcro authentication, I want to verify customer tokens locally via a standard JWKS endpoint, and to confirm a specific token's validity via a dedicated validation endpoint, so that I can protect resources and manage sessions without extra authenticated calls.

🎯 Definition of Done (DoD)

✔ Given a client requests GET /.well-known/jwks.json, then a valid JWKS containing the RS256 public key(s) is returned in standard format.
✔ Given a JWT issued after deployment, when it is verified with the public key from the JWKS endpoint, then the signature validates without any further Pelcro API call — and newly issued tokens use RS256.
✔ Given an auth.token is posted to the token-validation endpoint, then the response states whether it is valid, expired, or invalid, without requiring a separate authenticated request.
✔ Given a JWT issued before deployment (HS256), when presented to authenticated endpoints, then it is still accepted until existing tokens expire.
✔ This change will impact API — specifically the authentication endpoints (Core API) and token issuance.
✔ Limitations: local verification confirms signature and expiry only; revocation still requires the validation endpoint.

Rana Haleem

Team•

Jun 24

•

Merged request

•

1 vote

[Merged] Add Auth Token Validation Endpoint

[Merged into Customer Token Verification: JWKS Endpoint & Token Validation]

Problem Statement

Clients currently authenticate customers using the PelcroOpen Login API, which returns anauth.tokenupon successful authentication. However, there isno dedicated API endpoint to validate whether an existingauth.tokenis still valid or active.
Clients such asEnergy Intelneed a way toprogrammatically verify token validitywhen managing sessions or protecting resources across their systems. Without this capability, clients must rely on indirect methods (e.g., attempting authenticated requests) to determine whether a token is valid, which introduces unnecessary complexity and inefficiency.
A dedicated endpoint would provide aclear, standardized, and API-first methodto confirm whether anauth.tokenis valid, expired, or invalid.

User Story

As aPelcro API client (Energy Intel),
I want toverify whether anauth.tokenis valid via a dedicated API endpoint,
so that I cansecurely validate user sessions and control access to protected resources without making additional authenticated API calls.

Proposed Solution

Introduce anew API endpointthat validates anauth.tokenissued via the Open Login authentication flow.
The endpoint should:

Accept an auth.token
Verify whether the token:
- Exists
- Is valid
- Has not expired
- Has not been revoked
Return a clear validation response.

Definition of Done (DoD)

API Endpoint Implemented
- A new endpoint [clarify endpoint path] exists to validate auth.token.
Token Validation Logic
- Endpoint verifies:
  - Token existence
  - Token expiration
  - Revocation status
  - Associated customer.
Response Standardization
- Returns structured JSON indicating:
  - Token validity (true/false)
  - Reason if invalid
  - Optional attributes (customer ID, expiration timestamp).
Security Requirements
- Endpoint respects Pelcro authentication and rate-limiting policies.
- Tokens are validated without exposing sensitive data.
Documentation
- Endpoint documented in Pelcro API Docs.
- Example requests and responses included.
Testing
- Unit tests for validation logic.
- API tests covering:
  - Valid token
  - Expired token
  - Revoked token
  - Invalid token format.