Refresh an Access token

Refresh an Access token.

POST /oauth/token/refresh/

Headers

Name	Value
Authorization	Bearer Base64Encoded(Client ID:Client Secret)
Content-Type	application/json

Payload

refreshrequired

string

Refresh token to obtain new access token

Response

{
 "success": true,
 "message": "string",
 "access": "string",
 "refresh": "string",
 "expires_in": 0,
 "org_identifier": "string"
}

---

Upcoming Security Enhancement: Refresh Token Invalidation

Advance Security Notice

FreJun is introducing a security enhancement to tighten OAuth 2.0 token handling: Enforced Token Invalidation with Reuse Detection.

After a refresh token is rotated, the previous refresh token remains temporarily valid for 30 seconds to support concurrent requests and network retries. During this grace period, reuse of the previous token does not create another refresh token; instead, FreJun issues a new access token and returns the same currently active refresh token.

This implementation follows standard OAuth 2.0 security best practices, using refresh-token rotation and reuse detection to mitigate refresh-token replay.

OAuth Token Specifications

Token Type	Lifetime	Notes
Access Token	6 hours	Standard token lifetime for authenticating API requests
Refresh Token	60 days	Standard token lifetime for the active refresh token
Rotated Token Grace Period (Security Update)	30 seconds	Window during which a previously rotated token remains valid for in-flight requests

---

How the Grace Period Works

When a refresh request succeeds, FreJun generates a new refresh token (R2). To safely accommodate parallel application processes and temporary network retries, the previous token (R1) enters a 30-second grace period.

Initial Refresh:
  Client presents R1 ──► FreJun returns Access Token 1 + R2 (New active refresh token)
                         [R1 enters 30-second grace period]

Concurrent Requests (within 30 seconds using R1):
  Client presents R1
          ↓
  FreJun validates R1 is within its 30-second grace period
          ↓
  FreJun issues a NEW access token (e.g., Access Token 2, 3...)
          ↓
  FreJun returns the SAME active refresh token R2

After 30 seconds:
  R1 is permanently invalidated.

Concurrency & Retries

Because FreJun returns the same active refresh token (R2) rather than minting new ones during the grace period, all concurrent workers receive valid access tokens while converging on the same active refresh token (R2), preventing refresh-token rotation races.

---

Token Reuse Detection & Revocation

If a previously rotated refresh token is presented after the 30-second grace period, FreJun will treat this as a potential security incident (such as an attempted token replay attack).

Security Revocation

When an expired refresh token is reused after its grace period, FreJun immediately invalidates the entire OAuth token chain:

• The reused refresh token.
• All previously issued refresh tokens belonging to the token chain.
• The currently active refresh token.
• All active access tokens issued from that token chain.

Error Response

Requests made with an invalidated refresh token will return HTTP 401 Unauthorized:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "success": false,
  "message": "Refresh token has been revoked"
}

When a token chain is revoked:

1. Account administrators receive an automated security alert email.
2. The integration must complete the OAuth Authorization Flow to obtain new credentials.

---

Developer Verification Checklist

Before this security update is enforced:

1. Persist Tokens Dynamically: Replace your stored refresh token with the newly returned token after every successful refresh.
2. Store Refresh Tokens Securely: Persist the latest refresh token in a secure token store. Never hardcode refresh tokens in source code, .env files, or other static configuration.
3. Handle 401 Unauthorized Gracefully: Detect "Refresh token has been revoked" and trigger the re-authorization flow instead of retrying with the revoked token.