> ## Documentation Index
> Fetch the complete documentation index at: https://chargecloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How To

> Let's get your first API call going!

This page walks you through a complete first request to the Core API, from API key to a real resource call.

## API Key

To Use the Core API you require an API key. The API key can be created in the chargecloud OS.

An API Key consists of:

* **Public key**, used as the **username**
* **Private key**, used as the **password**

Treat the private key like a password. Do not share it, do not commit it to Git, and store it in a secrets manager or environment variables.

## Get an access token

Before you can call protected endpoints, you first need an OAuth access token.

### Request

<Tabs>
  <Tab title="HTTP Request">
    ```http theme={null}
    POST /api/v1/oauth/token HTTP/1.1
    Host: api.chargecloud.dev
    Content-Type: application/x-www-form-urlencoded

    username=PUBLIC_API_KEY&password=PRIVATE_API_KEY
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.chargecloud.dev/api/v1/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data "username=PUBLIC_API_KEY&password=PRIVATE_API_KEY"
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "access_token": "<string>",
  "refresh_token": "<string>",
  "token_type": "Bearer",
  "expires_in": 123
}
```

Copy the `access_token` value and send it with each request using the `Authorization` header:

* `Authorization: Bearer <access_token>`

## List locations

With a valid access token, you can call the Asset endpoints. The example below fetches all locations.

### Request

<Tabs>
  <Tab title="HTTP Request">
    ```http theme={null}
    GET /api/v1/assets/locations HTTP/1.1
    Host: api.chargecloud.dev
    Authorization: Bearer ACCESS_TOKEN
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://api.chargecloud.dev/api/v1/assets/locations" \
    -H "Authorization: Bearer ACCESS_TOKEN"
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "locations": [
    {
      "id": 1,
      "created_at": "2023-12-25",
      "updated_at": "2023-12-25",
      "modification_date": "2023-12-25",
      "controllers": [
        {
          "controller_uuid": "<string>"
        }
      ],
      "name": "<string>",
      "status": "in_questioning",
      "street": "<string>",
      "postal_code": "<string>",
      "city": "<string>",
      "country_code": "abw",
      "latitude": 123,
      "longitude": 123,
      "operator": "<string>",
      "operator_id": 1,
      "support_hotline_country": "abw",
      "support_hotline": "<string>",
      "publish": true,
      "identifier": "<string>",
      "house_number": "<string>",
      "district": "<string>",
      "rural_district": "<string>",
      "height": 1,
      "directions": "<string>",
      "description": "<string>",
      "website": "<string>",
      "comment": "<string>",
      "comment_usage_agreement": "<string>",
      "level_measurement": "<string>",
      "network_carrier": "<string>",
      "available_power": "<string>",
      "additional_conditions": "<string>",
      "contract_id": 1
    }
  ]
}
```

You have successfully completed your first Core API call.


## Related topics

- [Authentication](/authentication.md)
- [Getting Started](/index.md)
- [Overview](/best-practices/overview.md)