# API

## Everything starts with a token of trust

All API endpoints can be accessed via an API token that is tied to the permissions of a user account. You can also let them expire after some time.

### How to get a token?

1. Go to **Settings / Users**
2. Click **Create New Token**

<figure><img src="https://3709841693-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCeRlmJf2y704TpjpubE1%2Fuploads%2FydeWIeEUdeXtgjUUVj0Z%2Fimage.png?alt=media&#x26;token=7c25b113-772e-4d07-91c7-3cea67028a4f" alt=""><figcaption></figcaption></figure>

3. **Enter a name**, description, and expiration period
4. **Copy the token** (it's only shown once)

### How to use the token?

You have two ways. You either pass the token as a header with `API-KEY` or you pass it as a url parameter  in `api_token` . As a header is usually more secure because automated loggers don't store them, but in some places you can't set headers (e.g. dbt webhooks) and then you can use the URL parameter.

#### Via Headers

Call the user endpoint via command line interface.

```bash
# Basic API request with token
curl -H "API-KEY: dot-your_token_here" <https://[app or eu].getdot.ai/api/auth/me>
```

Call the user endpoint via Python.

```python
import requests
headers = {"API-KEY": "dot-your_token_here"}
response = requests.get("https://[app or eu].getdot.ai/api/auth/me", headers=headers)
```

#### Via URL - Parameters

For the following endpoints you can also use a URL based authentication:

* Sync connection
* Import external asserts
* Export conversation history

Call the endpoint only via url:

```bash
curl "https://{region}.getdot.ai/api/sync/{connection_type}/{connection_type}" \
     "?user_id={user}&api_token={api_token}"
```

## Learn More

{% content-ref url="api/commonly-used-endpoints" %}
[commonly-used-endpoints](https://docs.getdot.ai/developers/api/commonly-used-endpoints)
{% endcontent-ref %}

{% content-ref url="api/use-cases-and-scripts" %}
[use-cases-and-scripts](https://docs.getdot.ai/developers/api/use-cases-and-scripts)
{% endcontent-ref %}

{% content-ref url="api/all-api-endpoints" %}
[all-api-endpoints](https://docs.getdot.ai/developers/api/all-api-endpoints)
{% endcontent-ref %}