Token Rotation

To help customers manage expiring API Tokens without requiring manual token generation from the Smartflo portal, Smartflo provides a Token Rotation API.

The Token Rotation API allows customers to generate a new API Token using an existing active token, without requiring the customer to log in to the Smartflo portal.

This is particularly useful for customers using short-duration token validity options such as 1, 7, 15, 30, or 90 days, as the token can be rotated programmatically as part of their integration or token lifecycle management process.

Token Rotation Flow

The token rotation process replaces the existing active token with a newly generated token:

Token A → Rotate API → Token B

After successful rotation:

• Token A is marked as Superseded.
• Token B is marked as Active.
• Token B inherits the applicable configuration and security restrictions of Token A.

The rotation operation does not bypass or reset the security configuration associated with the original token.

Token Rotation API

Method: POST

Endpoint: https://api-smartflo.tatateleservices.com/v1/auth/rotate

Request Headers

Authorization: Bearer <token>
Content-Type: application/json

The existing active token provided in the Authorization header is used as the source token for rotation.

Successful Response

HTTP Status: 200 OK

{
  "success": true,
  "message": "Token refreshed successfully.",
  "access_token": "eyJ0eXAiOiJXXXXiLCJhbGciOiJIUzI1Ni...",
  "token_type": "bearer",
  "validity_days": 90
}

Response Parameters

Token Configuration During Rotation

The newly generated token retains the applicable configuration and security restrictions of the source token, including:

• Token validity configuration
• IP restrictions
• Scope restrictions, wherever applicable and supported
• Other applicable token specifications and security configurations

Token rotation does not reset, remove, or bypass security restrictions associated with the source token.

Example

A customer has an active portal token configured with a 90-day validity period and applicable IP restrictions. Instead of logging in to the Smartflo portal when the token needs to be replaced, the customer can call:

POST https://api-smartflo.tatateleservices.com/v1/auth/rotate
Authorization: Bearer <existing_active_token>

Smartflo generates a new token based on the applicable configuration of the existing token.

The resulting lifecycle is:

Existing Token → Rotate API → New Token

The existing token becomes Superseded, while the newly generated token becomes Active. The response returns the new token along with its applicable token category and validity configuration.

Token Validation

Before performing a token rotation, the API validates the source token provided in the Authorization header.

A new token is generated only when the source token is in an Active state. If the source token is expired, suspended, invalid, or blacklisted, the rotation request is rejected and a new token is not generated.

UI Behaviour

When a token is successfully rotated through the Token Rotation API:

• A new token entry is created in the Smartflo UI.
• The new token is associated with the appropriate token category and applicable configuration.
• The newly generated token is displayed according to the existing token-management behaviour.
• The source token is updated to Superseded.
• The newly generated token is displayed as Active.
• The existing token history and audit information reflect the token rotation event.

The UI should therefore provide visibility into both the source token and the newly generated token, allowing administrators to track the token lifecycle and rotation history.

Suspended Token Expiry

Tokens currently in Suspended status should automatically transition to Expired once their configured expiry date and time is reached.

Token Rotation vs. Token Refresh

The Token Rotation API is introduced specifically for rotating API Tokens generated from the Smartflo portal, while retaining their applicable configuration and security restrictions.

The existing POST /v1/auth/refresh API and its current behaviour remain unchanged.

Recommended Token Management

Customers using Smartflo API Tokens should incorporate token lifecycle management into their integration. For portal-generated tokens:

1. Select an expiry period based on the integration requirement.
2. Store the token securely in the customer application.
3. Monitor the token's validity and expiry.
4. Use the Token Rotation API to generate a replacement token when required.
5. Update the application with the newly generated token.
6. Ensure the previous token is no longer used after it has been superseded.

Using Token Rotation allows customers to manage token replacement programmatically and reduces the need for manual intervention through the Smartflo portal.