Auth

View on Github

Note: We are reducing our investment in CARTO for React and currently we discourage users from starting new projects with it.

CARTO for React is an opinionated framework with pre-built components and templates. This greatly speeds up the process to create React-based applications, but customization options are limited.

If you need further customization in React, or you want to build geospatial applications using Vue, Angular, or any other Javascript-based framework, we recommend going directly to the main CARTO for Developers documentation, including CARTO + deck.gl, which allows for maximum flexibility and scalability.

Package	Version	Downloads
@carto/react-auth

This package contains some OAuth utilities for implementing authentication and authorization against the CARTO 2 platform. If you are building an application with CARTO 3, you should use Auth0 React SDK instead of this package.

Components

OAuthCallback

React component to attend OAuth callbacks on /oauthCallback. Ensure you include that specific route in your application.

• Example:

import { OAuthCallback } from "@carto/react-auth";

// inside the proper routing config...
const routes = [
  /* ...some other routes and */
  { path: "/oauthCallback", element: <OAuthCallback /> },
];

Functions

useOAuthLogin

Hook to perform login against CARTO, with OAuth implicit flow and using a popup.

• Input:

Param	Type	Description
oauthApp	Object	OAuth parameters
oauthApp.clientId	string	Application client ID
oauthApp.scopes	Array.<string>	Scopes to request
oauthApp.authorizeEndPoint	string	Authorization endpoint
onParamsRefreshed	function	Function to call when params are refreshed

• Returns: function - A function to trigger oauth with a popup

• Example:

import { useOAuthLogin } from "@carto/react-auth";

const oauthApp = {
  clientId: "YOUR_OAUTH_CLIENT_ID",
  scopes: ["user:profile"],
  authorizeEndPoint: "https://carto.com/oauth2/authorize",
};

const onParamsRefreshed = (oauthParams) => {
  if (oauthParams.error) {
    console.error(`OAuth error: ${oauthParams.error}`);
  } else {
    console.log(oauthParams);
  }
};

const [handleLogin] = useOAuthLogin(oauthApp, onParamsRefreshed);
// handleLogin function should be later handled from UI to trigger the flow

Tip: Check CARTO for React templates for CARTO 2 for examples using this hook, where oauthApp data is managed within Redux store. For example, this is the Login page.