PayPal-PHP-Server-SDK/doc/auth/oauth-2-client-credentials-grant.md

OAuth 2 Client Credentials Grant

Documentation for accessing and setting credentials for Oauth2.

Auth Credentials

Name	Type	Description	Setter	Getter
OAuthClientId	string	OAuth 2 Client ID	oAuthClientId	getOAuthClientId()
OAuthClientSecret	string	OAuth 2 Client Secret	oAuthClientSecret	getOAuthClientSecret()
OAuthToken	OAuthToken|null	Object for storing information about the OAuth token	oAuthToken	getOAuthToken()
OAuthClockSkew	int	Clock skew time in seconds applied while checking the OAuth Token expiry.	oAuthClockSkew	-
OAuthTokenProvider	callable(OAuthToken, ClientCredentialsAuthManager): OAuthToken	Registers a callback for oAuth Token Provider used for automatic token fetching/refreshing.	oAuthTokenProvider	-
OAuthOnTokenUpdate	callable(OAuthToken): void	Registers a callback for token update event.	oAuthOnTokenUpdate	-

Note: Auth credentials can be set using ClientCredentialsAuthCredentialsBuilder::init() in clientCredentialsAuthCredentials method in the client builder and accessed through getClientCredentialsAuth method in the client instance.

Usage Example

Client Initialization

You must initialize the client with OAuth 2.0 Client Credentials Grant credentials as shown in the following code snippet. This will fetch the OAuth token automatically when any of the endpoints, requiring OAuth 2.0 Client Credentials Grant autentication, are called.

$client = PaypalServerSDKClientBuilder::init()
    ->clientCredentialsAuthCredentials(
        ClientCredentialsAuthCredentialsBuilder::init(
            'OAuthClientId',
            'OAuthClientSecret'
        )
    )
    ->build();

Your application can also manually provide an OAuthToken using the setter oAuthToken in ClientCredentialsAuthCredentialsBuilder object. This function takes in an instance of OAuthToken containing information for authorizing client requests and refreshing the token itself.

Adding OAuth Token Update Callback

Whenever the OAuth Token gets updated, the provided callback implementation will be executed. For instance, you may use it to store your access token whenever it gets updated.

$client = PaypalServerSDKClientBuilder::init()
    ->clientCredentialsAuthCredentials(
        ClientCredentialsAuthCredentialsBuilder::init(
            'OAuthClientId',
            'OAuthClientSecret'
        )
            ->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();

Adding Custom OAuth Token Provider

To authorize a client using a stored access token, set up the oAuthTokenProvider in ClientCredentialsAuthCredentialsBuilder along with the other auth parameters before creating the client:

$client = PaypalServerSDKClientBuilder::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();
                }
            )
    )
    ->build();