Technical Guide: Migration from OAuth 1 to OAuth V2

Required action: All endpoint references within the source code must be updated. It is recommended to use environment variables or a global "find and replace" procedure to reflect the TLD change from .it to .com.

3. Token Management Evolution

3.1 Endpoint Mapping

V2 adopts a pluralized RESTful naming convention for token resource management. The endpoint for token operations changes from /token to /tokens.

3.2 Creation and Parameters (TokenCreate)

In V2, the POST /tokens endpoint extends granular control beyond simple scopes and ttl fields. The following parameters defined in the TokenCreate schema are now supported: name (mnemonic identifier for audit logs), limit_total (maximum request threshold), limit_paid (maximum paid request limit), ips (authorized IP address whitelist), and wallet_limit (specific budget allocated from the global Wallet).

3.3 Update and Refresh-Token Flow

While in V1 the PATCH method was limited to partial metadata updates, in V2 the PATCH /tokens/{token} method is standardized to support the refresh-token rotation flow. This enables credential rotation and permission updates without invalidating the existing identifier, ensuring operational continuity and improved security.

3.4 JSON Structure Comparison

V2 returns the TokenDetail object (part of the TokenListOrDetail schema), integrating limits and metadata that were previously unavailable.

OAuth 1 Response (Legacy):

{
  "scopes": ["POST:valutometro.altravia.com/valutazione"],
  "expire": 1634223407,
  "token": "5f8711afe4754a532a7a8358",
  "success": true,
  "message": "",
  "error": null
}

OAuth V2 Response (TokenDetail):

{
  "name": "Production_Token_01",
  "token": "6f9822bgf5862b643b8b9469",
  "expire": 1735689600,
  "scopes": [
    {
      "domain": "imprese.openapi.it",
      "endpoint": "base",
      "method": "GET"
    }
  ],
  "limits": {
    "limit_total": 1000,
    "limit_paid": 500,
    "wallet_limit": 50.00
  },
  "ips": ["192.168.1.1"],
  "success": true
}

4. From Credit (V1) to Wallet (V2)

V2 introduces financial management through the Wallet module, ensuring transactional transparency. Balance inspection is now performed via GET /wallet, replacing the old /credit. Transaction traceability is ensured by GET /wallet/transactions, which provides access to transaction history. Unlike the static value in V1, transaction history in V2 is paginated, enabling detailed analysis for high-volume transactional accounts.

5. Monitoring Systems: From Counters to Advanced Statistics

The V1 /counters system, based on rigid time aggregations, has been replaced by the multidimensional /stats engine. V2 granularity enables aggregation by Token, IP, Domain, and Scope. Calls such as GET /stats/ips identify unique IP addresses, GET /stats/apis aggregates API usage by domain, and GET /stats/apis/{domain} provides an exact breakdown of scopes used within a specific domain. Integrated logs are also available for error visibility through /errors.

6. New Exclusive Features of OAuth V2

Version 2.0.0 introduces monitoring endpoints that were previously unavailable:

• Callbacks (/callbacks): Endpoint for monitoring and verifying the delivery status of callbacks generated by APIs.
• Subscriptions (/subscriptions): Management and inspection of active subscriptions associated with the account.
• Error Logs (/errors): Programmatic access to error logs (ErrorLog), essential for real-time integration debugging.

7. Quick Reference Table for Developers