How PayPal uses OAuth 2.0

The PayPal REST API uses the OAuth 2.0 protocol to authorize calls. OAuth is an industry-standard open standard for authorization used by many companies to provide secure access to protected resources.

Here is an overview of how the OAuth 2.0 auth flow works:

Image of OAuth 2.0 Sequence Flow for PayPal REST APIs

Note: The dotted line is not part of the API flow and is a step accomplished through the PayPal Developer site.

Application registration

Register your application by logging into the PayPal Developer site using a PayPal account, and by going to the My Apps & Credentials page. You will be issued a set of test credentials (client_id and secret) that you can use to authenticate your API calls using the OAuth 2.0 protocol.

Access token requests

You then obtain an access token for your application by sending a request to the /v1/oauth2/token endpoint. You must authenticate your access token request (using HTTP Basic Auth) with your application credentials obtained as described above. The client_id and secret becomes your user-id and password in HTTP Basic Auth.

Note: If you're using cURL, you can pass the client_id and secret as -u "client_id:secret". For information about how HTTP client libraries send these credentials, see the corresponding documentation.

PayPal acts as the authorization server and verifies your application credentials and returns an access token. The specific kind of access token that PayPal provides is a "Bearer Token". PayPal also provides the token type in the response, which indicates the type as Bearer.

API request authentication

When you make the API calls, you add the access token in the 'Authorization' header. Use this syntax, as defined in the OAuth 2.0 protocol:

Authorization: Token-Type Access-Token

Example: Authorization: Bearer EEwJ6tF9x5...4599F

Access token validity and expiration

You use PayPal-issued access tokens to access all REST API endpoints. These tokens have a finite lifetime.

Before you create a new token, re-use the access token until it expires. Also see our rate limiting guidelines.

To detect when an access token expires, you must write code to either:

  • Keep track of the expires_in value in the token response. The value is expressed in seconds.

  • Handle the 401 Unauthorized error response from the API endpoint when an expired token is detected.