Auto-Refresh OAuth 2.0 Tokens

APIMatic's SDKs support automated Auth-Token retrieval and refresh for APIs using OAuth 2.0 Grant Types. This feature enables the SDK to automatically fetch or refresh the auth-token before making any API call that requires it. By simply configuring OAuth 2.0 grant type credentials in the SDK client, users can eliminate the need for manual token management, ensuring smoother and more efficient API interactions.

note

This feature is currently limited to OAuth 2.0 Client Credentials Grant type.

Key Use Cases

• Maintaining seamless API access for long-lived client applications.
• Reducing the risk of authentication failures due to expired tokens.
• Enhancing user experience by avoiding manual token refresh procedures.

Configure Auth Token Auto-Refreshing in Your OpenAPI Definition

To enable token auto-refreshing, ensure that your OpenAPI definition includes:

1. A Security Scheme (e.g., OAuth2 with refresh token flow).
2. Detailed configuration for token endpoints, including refresh token URLs and parameters.

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        refreshToken:
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access
security:
  - OAuth2:
      - read
      - write

SDK Examples

TypeScript

const client = new SDKClient({
  clientCredentialsAuthCredentials: {
    oAuthClientId: 'OAuthClientId',
    oAuthClientSecret: 'OAuthClientSecret',
    oAuthTokenProvider: (lastOAuthToken: OAuthToken | undefined, authManager: ClientCredentialsAuthManager) => {
      // Add the callback handler to provide a new OAuth token
      // It will be triggered whenever the lastOAuthToken is undefined or expired
      var token = loadTokenFromDatabase();
      if (token === undefined) {
        return authManager.fetchToken();
      }
      return token;
    },
    oAuthOnTokenUpdate: (token: OAuthToken) => {
      // Add the callback handler to perform operations like save to DB or file etc.
      // It will be triggered whenever the token gets updated
      saveTokenToDatabase(token);
    }
  },
});

Java

SDKClient client = new SDKClient.Builder()
    .clientCredentialsAuth(new ClientCredentialsAuthModel.Builder(
            "OAuthClientId",
            "OAuthClientSecret"
        )
        .oAuthTokenProvider((lastOAuthToken, credentialsManager) -> {
            // Add the callback handler to provide a new OAuth token
            // It will be triggered whenever the lastOAuthToken is null or expired
            OAuthToken token = loadTokenFromDatabase();
            if (token == null) {
                return credentialsManager.fetchToken();
            }
            return token;
        })
        .oAuthOnTokenUpdate(oAuthToken -> {
            // Add the callback handler to perform operations like save to DB or file etc.
            // It will be triggered whenever the token gets updated
            saveTokenToDatabase(oAuthToken);
        })
        .build())
    .build();

Python

def _o_auth_token_provider(last_oauth_token, auth_manager):
    # Add the callback handler to provide a new OAuth token
    # It will be triggered whenever the last provided o_auth_token is null or expired
    o_auth_token = load_token_from_database()
    if o_auth_token is None:
        o_auth_token = auth_manager.fetch_token()
    return o_auth_token

client = SDKClient(
    client_credentials_auth_credentials=ClientCredentialsAuthCredentials(
        o_auth_client_id='OAuthClientId',
        o_auth_client_secret='OAuthClientSecret',
        o_auth_scopes=[
            OAuthScopeEnum.READ_SCOPE,
            OAuthScopeEnum.WRITE_SCOPE
        ],
        o_auth_token_provider=_o_auth_token_provider,
        o_auth_on_token_update=(lambda o_auth_token:
                                # Add the callback handler to perform operations like save to DB or file etc.
                                # It will be triggered whenever the token gets updated
                                save_token_to_database(o_auth_token))
    )
)

.NET

SdkClient client = new SdkClient.Builder()
    .ClientCredentialsAuth(
        new ClientCredentialsAuthModel.Builder(
            "OAuthClientId",
            "OAuthClientSecret"
        )
        .oAuthTokenProvider(async (token, credentialsManager) =>
        {
            // Add the callback handler to provide a new OAuth token
            // It will be triggered whenever the lastOAuthToken is undefined or expired
            return LoadTokenFromDatabase() ?? await FetchTokenAsync()
        })
        .oAuthOnTokenUpdate(token -> 
        {
            // It will be triggered whenever the token gets updated
            SaveTokenToDatabase(token);
        })
        .Build())
    .Build();

Go

client := Sdkclient.NewClient(
    Sdkclient.CreateConfiguration(
        Sdkclient.WithClientCredentialsAuthCredentials(
            Sdkclient.NewClientCredentialsAuthCredentials(
                "OAuthClientId",
                "OAuthClientSecret",
            ).
            WithOAuthOnTokenUpdate(func(oAuthToken models.OAuthToken) {
                // Add the callback handler to perform operations like save to DB or file etc.
                // It will be triggered whenever the token gets updated
                saveTokenToDatabase(oAuthToken)
            }).
            WithOAuthTokenProvider(func(lastOAuthToken models.OAuthToken, authManager ClientCredentialsAuthManager) models.OAuthToken {
                // Add the callback function handler to provide a new OAuth token
                // It will be triggered whenever the lastOAuthToken is undefined or expired
                oAuthToken := loadTokenFromDatabase()
                if oAuthToken.AccessToken == "" {
                    if token, err := authManager.FetchToken(context.TODO()); err == nil {
                        return token
                    }
                }
                return oAuthToken
            }),
        ),
    ),
)

PHP

$client = SdkClientBuilder::init()
    ->clientCredentialsAuthCredentials(
        ClientCredentialsAuthCredentialsBuilder::init(
            'OAuthClientId',
            'OAuthClientSecret'
        )
            ->oAuthTokenProvider(
                function (?OAuthToken $lastOAuthToken, ClientCredentialsAuthManager $authManager): OAuthToken {
                    // Add the callback handler to provide a new OAuth token.
                    // It will be triggered whenever the lastOAuthToken is null or expired.
                    return $this->loadTokenFromDatabase() ?? $authManager->fetchToken();
                }
            )
            ->oAuthOnTokenUpdate(
                function (OAuthToken $oAuthToken): void {
                    // Add the callback handler to perform operations like save to DB or file etc.
                    // It will be triggered whenever the token gets updated.
                    $this->saveTokenToDatabase($oAuthToken);
                }
            )
    )
    ->build();

Ruby

def _o_auth_token_provider(last_oauth_token, auth_manager)
    # Add the callback handler to provide a new OAuth token
    # It will be triggered whenever the last provided o_auth_token is null or expired
    o_auth_token = load_token_from_database()
    o_auth_token = auth_manager.fetch_token() if o_auth_token is nil?
    return o_auth_token
end

client = SDKClient.new(
  client_credentials_auth_credentials: ClientCredentialsAuthCredentials.new(
    o_auth_client_id: 'OAuthClientId',
    o_auth_client_secret: 'OAuthClientSecret',
    o_auth_token_provider: _o_auth_token_provider,                    
    o_auth_on_token_update: Proc.new { | o_auth_token | 
                              # Add the callback handler to perform operations like save to DB or file etc.
                              # It will be triggered whenever the token gets updated
                              save_token_to_database(o_auth_token)
                            }
  )
)

Best Practices

• Ensure refresh tokens are stored securely to prevent unauthorized access.
• Validate the scope and permissions of the refreshed token.