# HDX core concepts

### API tokens

An API token is a unique key that authenticates users when making requests to HDX programmatically. It works like a password for the API, allowing you to create, update, or delete data depending on your permissions. Permissions are dependent on your level of access to various organizations (admin, editor, or member). 

API tokens are connected to your HDX account and must be kept secure. Never share them publicly as they also allow *write* functionality.

#### Creating an HDX API token

* Sign into HDX [data.humdata.org](http://data.humdata.org/).
* Navigate to your profile settings.

<div data-with-frame="true"><figure><img src="/files/NQrOOVbD2toxwHYjOYWQ" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/iuQ8F9r4zpXzoR1uTrxx" alt=""><figcaption></figcaption></figure></div>

* Select “Manage API tokens”, and then **generate your token**.

<div data-with-frame="true"><figure><img src="/files/lN1hTJDvKv4xzJnTbIvQ" alt=""><figcaption></figcaption></figure></div>

* **Copy your token** (you will not be able to view it again) and save it either in your password manager or other secure location.

#### Data resources <a href="#data-resources" id="data-resources"></a>

On HDX, a *data resource* is an individual data file or API endpoint that belongs to a dataset. Each dataset can contain one or more resources, for example a CSV file, Excel spreadsheet, shapefile, or an API feed. Resources are the actual data objects that users download or query.To understand how resources fit into the overall structure of HDX, it helps to see their relationship to datasets and organizations:

**Relationship of HDX entities**

Organization

&#x20;          └── Dataset

&#x20;                              └── Resource(s)

* **Organization:** The publisher or owner of data (e.g., OCHA).
* **Dataset:** A collection of related information published by an organization (e.g., “Food Prices in Kenya”).
* **Resource:** The actual data file or service within a dataset (e.g., CSV file of market prices, shapefile of locations).

Each available HDX resource is identified by a **unique resource ID**, which you’ll need to include in API requests. Resource IDs are the form of a 36 character UUID, for example: `f3f203bf-d29b-4b88-a724-25ab32a67543`. You can find a resource ID through the dataset page UI, or by using the HDX metadata API.

**Finding a resource ID: Dataset page**

You can locate a resource’s unique ID directly from its dataset page in the HDX UI. Each resource listed under **Data and Resources** displays its Resource ID beneath the title. Clicking the copy icon next to the ID will copy the full UUID to your clipboard, making it easy to use in scripts, API calls, or downstream analysis.&#x20;

This is the quickest way to retrieve the exact identifier for a resource you want to query programmatically.

<div data-with-frame="true"><figure><img src="/files/ivo50qm6Iqkoz1HedV8X" alt=""><figcaption></figcaption></figure></div>

**Finding a resource ID: HDX Metadata API**

For predictable dataset names, you can also access `resource_ids` through the [HDX metadata API](https://data.humdata.org/dataset/2048a947-5714-4220-905b-e662cbcd14c8/resource/3b675846-d01c-4fc9-b577-b7d426d2a598/download/hdx-ckan-api-cookbook.pdf?_gl=1*mlbc9r*_ga*NjQxMDQxNjkxLjE3NDM2NzcxNjc.*_ga_E60ZNX2F68*czE3NTY3Mzg1MjUkbzE5MCRnMSR0MTc1NjczOTI5NSRqNjAkbDAkaDA.) endpoint which allows you to search the metadata of the data in our catalogue. See instructions below:

1. **Find the dataset name:** Go to the dataset page and find the name in the URL. You can also search using the HDX metadata API (see cookbook above) which can also generate the dataset name.
   1. Example: `https://data.humdata.org/dataset/`**`zwe-rainfall-subnational`**
2. **Retrieve package and resource metadata:** Use the `package_show` endpoint to fetch details about the dataset, including all its associated resources and the id. See example below.
   1. Example: `https://data.humdata.org/api/3/action/package_show?id=zwe-rainfall-subnational`
3. **Locate the resource in the response:** From the response, identify the resource that corresponds to the structured data you're interested in. There you will find the `resource_id`.

   1. Example:

   <div data-with-frame="true"><figure><img src="/files/NRh3F5XVOCWonOyaZlC2" alt=""><figcaption></figcaption></figure></div>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.humdata.org/build/overview/hdx-core-concepts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.