# Quick Start

Use this section to understand the prerequisites and steps for integrating with Data 360 APIs.

:::note
To quickly make calls to the Data 360 API, use the [Postman collection](https://www.postman.com/salesforce-developers/salesforce-developers/collection/vkln4gx/salesforce-data-cloud-apis). For more information and a video tutorial, see [Make Data 360 REST API Calls with Postman](https://developer.salesforce.com/docs/data/data-cloud-dev/guide/dc-apis-postman.md?q=postman).
:::

## Step 1: Familiarize Yourself with Data 360

Explore the [Data Cloud Online Help](https://help.salesforce.com/articleView?id=customer360\_a.htm) if you're unfamiliar with the application.

## Step 2: Set Up Data 360

Before you can use Data 360 APIs, you must configure the application. To set up the application, see [Data Cloud Implementation Overview Guide](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/DataCloud_Overview.pdf).

Your org must be provisioned with a Data 360 license, and users must have the **Minimum Access - API Only Integrations** profile assigned and appropriate permissions to access required objects in Data 360. See [Data Cloud Standard Permission Sets](https://help.salesforce.com/s/articleView?id=data.c360\_a_userpermissions.htm\&type=5).

If you’re using an existing Data 360 instance, confirm with your admin that your user profile has permissions to use Data 360 APIs.

## Step 3: Set Up Data Sources

After you create your Data 360 instance, you can control the scope of data ingestion and activation from within the instance.

Set up your data sources by [creating an app connector](https://help.salesforce.com/articleView?id=data.c360\_a_web_mobile_app_connector.htm) in the Data 360 app. Configure data streams to ingest data for data mapping and segments.

## Step 4: Set Up an External Client App

Set up an external client app to authenticate and request access to Data 360 APIs. The external client app enables standard OAuth protocols for authentication and authorization and is a newer version of a connected app. Follow the instructions in [Create an External Client App](https://help.salesforce.com/s/articleView?id=xcloud.create_a_local_external_client_app.htm\&type=5) and configure the app depending on the type of OAuth 2.0 flow you intend to use to authenticate to the Salesforce platform and how you want to implement it. For information on configuring an external client app for different OAuth 2.0 flows, see [Configure the External Client App OAuth Settings](https://help.salesforce.com/s/articleView?id=xcloud.configure_external_client_app_oauth_settings.htm\&type=5).

In general, you must select **Enable OAuth** under **OAuth Settings** and then select the necessary OAuth scopes. These scopes define the permissions for the external client app and are granted as tokens after the app is authorized.

- Perform ANSI SQL queries on Data Cloud data (**cdp_query_api**): The `cdp_query_api` scope allows ANSI SQL queries of Data Cloud data on behalf of the user.
- Manage Data Cloud profile data (**cdp_profile_api**): The `cdp_profile_api` scope allows you to manage Data Cloud profile records.
- Manage Data Cloud Ingestion API data (**cdp_ingest_api**): The `cdp_ingest_api` scope allows access to manage Data Cloud Ingestion API data.
- Perform requests at any time (**refresh_token**): The `refresh_token` scope allows a refresh token to be returned when the requesting client is eligible to receive one. With a refresh token, the app can interact with the user’s data while the user is offline.
- Manage user data via APIs (**api**): The `api` scope allows access to the current logged-in user’s account using APIs, such as REST API and Bulk API 2.0.

:::important
After creating the external client app, navigate to the **Settings** tab of the app, click **Consumer Key and Secret** under **OAuth Settings**, and copy the *Consumer Key* and *Consumer Secret*. You need to use these details to authenticate to Data 360 APIs.
:::

For example, you can configure the external client app to use the web server OAuth 2.0 flow to authenticate to the Salesforce platform. For more information, see [Configure a Web Server Flow](https://help.salesforce.com/s/articleView?id=xcloud.configure_web_server_flow_for_external_client_apps.htm).

## Step 5: Authenticate to the Data 360 API

Authentication to the Data 360 API is a two-step process. First, you must authenticate to the Salesforce platform to obtain a Salesforce access token. Then, you use that Salesforce access token to authenticate to the Data 360 tenant for a Data 360 access token. You can then use the Data 360 access token to make API calls to the Data 360 API.

### Authenticate to the Salesforce Platform

To use the OAuth 2.0 web server flow to authenticate to the Salesforce platform, perform these settings in the external client app:

- For simplicity, disable **Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows** in the external client app. Depending on the OAuth 2.0 flow type you intend to use, you must configure the required settings in the external client app. For more information, see [Configure the External Client App OAuth Settings](https://help.salesforce.com/s/articleView?id=xcloud.configure_external_client_app_oauth_settings.htm\&type=5).

- To authenticate to the Salesforce platform, you need a callback URL where Salesforce sends the authorization code after successful authentication. You can either set up a local server (like `localhost:3000`) for testing or use your actual client URL. You must use the same URL as the callback URL in your external client app.

To authenticate to the Salesforce platform:

1. Initiate authorization and retrieve the Salesforce authorization code.

   a. Navigate to this URL in your web browser.

   ```
   https://MY_DOMAIN_NAME/services/oauth2/authorize?response_type=code&client_id={CONSUMER_KEY_OF_YOUR_EXTERNAL_CLIENT_APP}&redirect_uri=http://localhost:3000/callback&scope=api cdp_query_api cdp_profile_api cdp_ingest_api
   ```

   :::note
   In this section, the commands use placeholder variables written in uppercase letters with underscores separating the words.
   :::

   b. In the Salesforce login page, log in using your credentials. After successful login, a consent screen appears.

   c. Click **Allow** to authorize access to Data Cloud APIs. You are redirected to the web page of the redirect URL specified in your request.

   d. Copy the `Salesforce OAuth code` displayed on the web page to use it in the next step.

2. Exchange the OAuth code obtained in the previous step for the Salesforce access token.

   **Request**

   ```
   curl -X POST "https://MY_DOMAIN_NAME/services/oauth2/token" \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -d "grant_type=authorization_code" \
   -d "code=SALESFORCE_OAUTH_CODE" \
   -d "client_id=CONSUMER_KEY_OF_YOUR_EXTERNAL_CLIENT_APP" \
   -d "client_secret=CONSUMER_SECRET_OF_YOUR_EXTERNAL_CLIENT_APP" \
   -d "redirect_uri=http://localhost:3000/callback"
   ```

   **Response**

   ```json
   {
     "access_token": "SALESFORCE_ACCESS_TOKEN",
     "signature": "Y4glTxhJzt9phzmZJebo4xmvRHZ9uGNvZpq/oIVvkpw=",
     "scope": "cdp_ingest_api api cdp_profile_api",
     "instance_url": "https://orgfarm-1dc4e302d3.test1.my.pc-rnd.salesforce.com",
     "id": "https://login.test1.pc-rnd.salesforce.com/id/00DSB00000VMDJJ2A5/005SB00000O3tYPYAZ",
     "token_type": "Bearer",
     "issued_at": "1748776670012"
   }
   ```

3. Copy the `SALESFORCE_ACCESS_TOKEN` to use it in the next step.

### Authenticate to the Data 360 Tenant

1. Exchange the `SALESFORCE_ACCESS_TOKEN` for the Data Cloud access token.

   **Request**

   ```
   curl -X POST \
   --url 'https://MY_DOMAIN_NAME/services/a360/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data 'grant_type=urn:salesforce:grant-type:external:cdp&subject_token=SALESFORCE_ACCESS_TOKEN&subject_token_type=urn:ietf:params:oauth:token-type:access_token&dataspace=Human_Resources'
   ```

   **Response**

   ```json
   {
     "access_token": "DATA_CLOUD_ACCESS_TOKEN",
     "instance_url": "DATA_CLOUD_INSTANCE_URL",
     "token_type": "Bearer",
     "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
     "expires_in": 7060
   }
   ```

2. Copy these values from the response to use in the Data 360 API requests.

- `DATA_CLOUD_ACCESS_TOKEN`: The token used to access Data Cloud resources.
- `DATA_CLOUD_INSTANCE_URL`: The tenant-specific endpoint where Data 360 API requests are sent.

## Step 6: Make a Sample API call

After you've acquired your org-specific Data 360 endpoint (`DATA_CLOUD_INSTANCE_URL`), use it for your organization's Data 360 API calls.

Let's make a sample API call to get the metadata of your Data 360 tenant.

**Request**

```
curl -X GET \
--location 'https://DATA_CLOUD_INSTANCE_URL/api/v1/metadata' \
--header 'Authorization: Bearer DATA_CLOUD_ACCESS_TOKEN'
```