Authorization

An overview of the clientToken

Understanding Authorization with clientToken

To initialize the SDK securely, a clientToken must be generated server-side and passed to your front-end. This token ensures that all API requests made by the SDK on your behalf are authenticated and protected.

The SDK clientToken is a publicly available universal access token (UAT) to use for the buyer's SDK session. This token is browser safe and is a short-lived token with a TTL of 15 minutes. There is no refresh token, after it expires you must make a new token.

Security Model

We've designed the clientToken to prioritize security by leveraging the following safeguards:

Domain Binding: The token is bound to your domain to prevent unauthorized usage elsewhere, minimizing the risk of impersonation attacks.
Cryptographic Security: The payload is cryptographically secured with a digital signature to ensure its integrity.

Create a route handler to return a clientToken to your frontend

This example assumes you're using Node.js with Express. In the future we'll add support for more backend languages.

This route will serve as an endpoint for retrieving a browser-safe clientToken from PayPal.

In upcoming steps, a helper function (e.g. getBrowserSafeClientToken()) will be implemented and invoked here to:

Authenticate with PayPal using secure server-side credentials.
Generate a client token appropriate for frontend usage.
Return the token to the browser without exposing sensitive keys.

This endpoint will eventually be consumed by the frontend to initialize PayPal SDK components such as different payment buttons.

app.get(
  "/paypal-api/auth/browser-safe-client-token",
  async (_req: Request, res: Response) => {
    // Right now, this block does nothing
    // In the next step we'll create a helper function to generate our clientToken
    // And finally we'll call it in this block, and return to the client
  },
);

Create a helper function to generate a clientToken

This function securely retrieves a browser-safe clientToken from PayPal's OAuth service using your PayPal sandbox credentials.

It performs the following steps:

Encodes your PAYPAL_SANDBOX_CLIENT_ID and PAYPAL_SANDBOX_CLIENT_SECRET into a Base64-encoded string for Basic Auth.
Sends a request to PayPal's requestToken method (from the Server SDK) to obtain a client token, using the response_type of "client_token".
Returns the parsed JSON response and the HTTP status code.
Handles errors gracefully by checking if the error is a PayPal ApiError, and returns the appropriate response object.

This token can then be safely passed to client-side code to initialize PayPal v6 Web SDKs (e.g. for rendering button), without exposing sensitive credentials in the browser.

export async function getBrowserSafeClientToken() {
  try {
    // Your PAYPAL_SANDBOX_CLIENT_ID & PAYPAL_SANDBOX_CLIENT_SECRET
    // are env variables that you can get from your developer dashboard.
    const auth = Buffer.from(
      `${PAYPAL_SANDBOX_CLIENT_ID}:${PAYPAL_SANDBOX_CLIENT_SECRET}`,
    ).toString("base64");

    // oAuthAuthorizationController is imported from the PayPal Server SDK
    // You can find more info here: https://developer.paypal.com/serversdk/java/getting-started/how-to-get-started
    const { body, statusCode } =
      await oAuthAuthorizationController.requestToken(
        {
          authorization: `Basic ${auth}`,
        },
        { response_type: "client_token" },
      );

    return {
      jsonResponse: JSON.parse(String(body)),
      httpStatusCode: statusCode,
    };
  } catch (error) {
    if (error instanceof ApiError) {
      const { statusCode, body } = error;
      return {
        jsonResponse: JSON.parse(String(body)),
        httpStatusCode: statusCode,
      };
    } else {
      throw error;
    }
  }
}

This route handler generates and returns a browser-safe PayPal client token to the frontend.

How It Works:

It calls the getBrowserSafeClientToken() helper to securely request a client token from PayPal's OAuth API using server-side credentials.
On success, it sends the parsed JSON response and status code back to the client.
If the token request fails, it logs the error server-side and responds with a 500 Internal Server Error and a generic error message.

This endpoint is intended for use by client-side PayPal SDKs, allowing them to initialize payment flows without exposing sensitive credentials.

app.get(
  "/paypal-api/auth/browser-safe-client-token",
  async (_req: Request, res: Response) => {
    try {
      const { jsonResponse, httpStatusCode } =
        await getBrowserSafeClientToken();  // <--- The helper you created above
      res.status(httpStatusCode).json(jsonResponse);
    } catch (error) {
      console.error("Failed to create browser safe access token:", error);
      res
        .status(500)
        .json({ error: "Failed to create browser safe access token." });
    }
  },
);

Taking things further

The clientToken helps keep your SDK instance safe and secure. But its just the first step into your integration with PayPal SDKs. Now that you know how to generate your clientToken, you can proceed with completing your integration.

If you'd like to jump straight to the code and see a full E2E example, see our example repo here.

An overview of the clientToken

Understanding Authorization with clientToken

Security Model

We've designed the clientToken to prioritize security by leveraging the following safeguards:

Domain Binding: The token is bound to your domain to prevent unauthorized usage elsewhere, minimizing the risk of impersonation attacks.
Cryptographic Security: The payload is cryptographically secured with a digital signature to ensure its integrity.

Create a route handler to return a clientToken to your frontend

This example assumes you're using Node.js with Express. In the future we'll add support for more backend languages.

This route will serve as an endpoint for retrieving a browser-safe clientToken from PayPal.

In upcoming steps, a helper function (e.g. getBrowserSafeClientToken()) will be implemented and invoked here to:

Authenticate with PayPal using secure server-side credentials.
Generate a client token appropriate for frontend usage.
Return the token to the browser without exposing sensitive keys.

This endpoint will eventually be consumed by the frontend to initialize PayPal SDK components such as different payment buttons.

app.get(
  "/paypal-api/auth/browser-safe-client-token",
  async (_req: Request, res: Response) => {
    // Right now, this block does nothing
    // In the next step we'll create a helper function to generate our clientToken
    // And finally we'll call it in this block, and return to the client
  },
);

Create a helper function to generate a clientToken

This function securely retrieves a browser-safe clientToken from PayPal's OAuth service using your PayPal sandbox credentials.

It performs the following steps:

Encodes your PAYPAL_SANDBOX_CLIENT_ID and PAYPAL_SANDBOX_CLIENT_SECRET into a Base64-encoded string for Basic Auth.
Sends a request to PayPal's requestToken method (from the Server SDK) to obtain a client token, using the response_type of "client_token".
Returns the parsed JSON response and the HTTP status code.
Handles errors gracefully by checking if the error is a PayPal ApiError, and returns the appropriate response object.

This token can then be safely passed to client-side code to initialize PayPal v6 Web SDKs (e.g. for rendering button), without exposing sensitive credentials in the browser.

export async function getBrowserSafeClientToken() {
  try {
    // Your PAYPAL_SANDBOX_CLIENT_ID & PAYPAL_SANDBOX_CLIENT_SECRET
    // are env variables that you can get from your developer dashboard.
    const auth = Buffer.from(
      `${PAYPAL_SANDBOX_CLIENT_ID}:${PAYPAL_SANDBOX_CLIENT_SECRET}`,
    ).toString("base64");

    // oAuthAuthorizationController is imported from the PayPal Server SDK
    // You can find more info here: https://developer.paypal.com/serversdk/java/getting-started/how-to-get-started
    const { body, statusCode } =
      await oAuthAuthorizationController.requestToken(
        {
          authorization: `Basic ${auth}`,
        },
        { response_type: "client_token" },
      );

    return {
      jsonResponse: JSON.parse(String(body)),
      httpStatusCode: statusCode,
    };
  } catch (error) {
    if (error instanceof ApiError) {
      const { statusCode, body } = error;
      return {
        jsonResponse: JSON.parse(String(body)),
        httpStatusCode: statusCode,
      };
    } else {
      throw error;
    }
  }
}

This route handler generates and returns a browser-safe PayPal client token to the frontend.

How It Works:

It calls the getBrowserSafeClientToken() helper to securely request a client token from PayPal's OAuth API using server-side credentials.
On success, it sends the parsed JSON response and status code back to the client.
If the token request fails, it logs the error server-side and responds with a 500 Internal Server Error and a generic error message.

This endpoint is intended for use by client-side PayPal SDKs, allowing them to initialize payment flows without exposing sensitive credentials.

app.get(
  "/paypal-api/auth/browser-safe-client-token",
  async (_req: Request, res: Response) => {
    try {
      const { jsonResponse, httpStatusCode } =
        await getBrowserSafeClientToken();  // <--- The helper you created above
      res.status(httpStatusCode).json(jsonResponse);
    } catch (error) {
      console.error("Failed to create browser safe access token:", error);
      res
        .status(500)
        .json({ error: "Failed to create browser safe access token." });
    }
  },
);

Taking things further

If you'd like to jump straight to the code and see a full E2E example, see our example repo here.

Authorization

An overview of the clientToken

Understanding Authorization with clientToken

Security Model

Create a route handler to return a clientToken to your frontend

Create a helper function to generate a clientToken

How It Works:

Taking things further

On this page

On this page

On this page

Authorization

An overview of the clientToken

Understanding Authorization with clientToken

Security Model

Create a route handler to return a clientToken to your frontend

Create a helper function to generate a clientToken

How It Works:

Taking things further

On this page

On this page

Authorization

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Authorization

On this page

On this page