REST API authentication and headers

With each API call, you’ll need to set request headers, including an OAuth 2.0 access token. Get an access token by using the OAuth 2.0 client_credentials token grant type with your clientId:secret as your Basic Auth credentials. For more information, see Make your first call. You can use your Sandbox access token to try any of the code in this reference.

Authorization When requesting an access token, send the value as the HTTP Basic Authentication credentials using your clientId and secret. (If using cURL, you can specify them as -u "clientId:secret".) When calling APIs, send the value as the OAuth 2.0 access token with the authentication type set as Bearer (Example: Authorization: Bearer <Access-Token>). Required.
Accept Set to application/json. Required.
PayPal-Request-Id Contains a unique ID that you generate that can be used for enforcing idempotency. Note: Omitting this header increases the risk of duplicate transactions.
PayPal-Partner-Attribution-Id Use this header if you are a PayPal partner. Specify a unique BN Code to receive revenue attribution. To learn more or to request a BN Code, contact your Partner Manager or visit the PayPal Partner Portal.
PayPal-Client-Metadata-Id PayPal uses this Client Metadata ID to verify that the payment is originating from a valid, user-consented device+application. This helps reduce fraud and decrease declines. Transactions that do not include a Client Metadata ID are not eligible for PayPal Seller Protection. See future payments for further details about initiating a pre-consented payment from a mobile device.

OAuth Request / Response

Use the OAuth request to retrieve an access token for use with your payments calls.

For authentication and authorization related to Identity, learn how to obtain a user’s consent.

Requests

Include the <Client-Id>:<Secret> as your Basic Auth credentials.

Tip: Learn more about how PayPal uses OAuth 2.0.

Property Type Description
grant_type string Token grant type. Must be set to client_credentials. Required.
content-type string Set to application/x-www-form-urlencoded for access token requests. This is done by default in cURL calls and is not shown in the request sample, but you may need to explicitly set this for non-cURL implementations.

Request sample

curl https://api.sandbox.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "<Client-Id>:<Secret>" \
  -d "grant_type=client_credentials"

Response

Property Type Description
scope string Scopes expressed in the form of resource URL endpoints. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings.
Value assigned by PayPal.
access_token string The access token issued by PayPal. The access token will expire (see expires_in), after which you’ll have to request a new access token.
Value assigned by PayPal.
token_type string The type of the token issued as described in OAuth2.0 RFC6749, Section 7.1. Value is case insensitive.
Value assigned by PayPal.
expires_in integer The lifetime in seconds of the access token.
Value assigned by PayPal.

Response sample

{
  "scope": "https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://api.paypal.com/v1/vault/credit-card/.*",
  "access_token": "EEwJ6tF9x5WCIZDYzyZGaz6Khbw7raYRIBV_WxVvgmsG",
  "token_type": "Bearer",
  "app_id": "APP-6XR95014BA15863X",
  "expires_in": 28800
}

You obtain a user’s consent to make Identity API calls on their behalf by redirecting them to the authorization endpoint. See Identity API calls for more information.

Authorization endpoint:

Live: https://www.paypal.com/webapps/auth/protocol/openidconnect/v1/authorize

Sandbox: https://www.sandbox.paypal.com/webapps/auth/protocol/openidconnect/v1/authorize

Note: The live environment also supports the optional inclusion of a 2-letter ISO-3166-1 country code: https://www.paypal.com/<2-letter-country-code>/webapps/auth/protocol/openidconnect/v1/authorize

This results in a localized page if the content has been translated for the app, and if the language is left-to-right.

Invoke the login flow from the application to Log In with PayPal with following URL, using browser redirect (HTTP 302).

Property Type Description
client_id string Unique client identifier obtained through the application registration process. Required.
response_type string Set to code to request that an authorization code be sent back to the application return URL (recommended, as the access tokens are not visible in the user-agent). Set to token to return a token, which is used mostly by public clients, such as JavaScript or mobile applications. Set to id_token for session assertion associated with the user’s authentication (e.g., used in remote procedure calls for explicit session management such as logout).
scope string URL-encoded, space-separated list of requested scope URIs. For example (URL-encoded): “profile+email+address”. For a list of possible values, see the attributes table.
redirect_uri string Application return URL where the authorization code is sent. The specified redirect_uri must match the return URL registered for your app on the My Apps & Credentials page of the PayPal Developer site. All parts of the specified redirect_uri, including protocol, host, port, context path, and query parameter names and values must match with the exception of the state parameter. You can use the state parameter to pass information that was not known at the time the return URL for your app was registered. The state parameter must be URL encoded and Base64 encoded.
nonce string An opaque random identifier to mitigate replay attacks. A simple function would be: (timestamp + Base64 encoding (random\[16\]))
state string Any state parameter that may be required by the application to know the request context.

The Log In with PayPal authorization endpoint validates the authorization/authentication request and directs the user to log in. After successful login, a consent message is displayed to the user. A user consent grants the requesting application access to the user’s PayPal attributes, as indicated by the scope specified in the request.

Return To Application

Once consent is granted, PayPal redirects (HTTP 302) the user back to the return URL with an authorization code appended to the URL. Use the authorization code to obtain a refresh token and initial access token.

https://www.sandbox.paypal.com/webapps/auth/protocol/openidconnect/v1/authorize
  ?client_id=<Client-Id>
  &amp;response_type=code
  &amp;scope=profile+email+address+phone
    +https%3A%2F%2Furi.paypal.com%2Fservices%2Fpaypalattributes
  &amp;redirect_uri=http://example.com/myapp/return.php

http://example.com/myapp/return.php?scope=profile+email+address
  +phone+https%3A%2F%2Furi.paypal.com%2Fservices%2Fpaypalattributes
  &amp;code=<Authorization-Code>
back to top