# Login

With auth enabled, you have to retrieve a JWT token before you can access the API calls.

## Username/password login

Send the username and password, as defined in [api.auth.username](https://docs.datarhei.com/core/api/pages/BVeGjgPvhjHjN3ThePBj#auth.username-string) and [api.auth.password](https://docs.datarhei.com/core/api/pages/BVeGjgPvhjHjN3ThePBj#auth.password-string), in the body of the request to the `/api/login` endpoint in order to obtain valid access and refresh JWT.

Example:

{% tabs %}
{% tab title="Curl" %}

```bash
curl http://127.0.0.1:8080/api/login \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -X POST \
   -d '{
         "username": "YOUR_USERNAME",
         "password": "YOUR_PASSWORD"
      }'
```

On successful login, the response looks like this:

```bash
{
   "access_token": "eyJz93a...k4laUWw",
   "refresh_token": "eyJz93a...k4laUWx"
}
```

Use the `access_token` in all subsequent calls to the `/api/v3/` endpoints, e.g.

```bash
curl http://127.0.0.1:8080/api/ \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer eyJz93a...k4laUWw' \
   -X GET
```

The expiry date is stored in the payload of the access token `exp` field, or the seconds until it expires is stored in the field `exi`.

In order to obtain a new access token, use the `refresh_token` for a call to `/api/login/refresh`:

```bash
curl http://127.0.0.1:8080/api/login/refresh \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer eyJz93a...k4laUWx' \
   -X GET
```

After the refresh token expires, you have to login again with your username and password.
{% endtab %}

{% tab title="PyClient" %}

```python
from core_client import Client

client = Client(
    base_url="http://127.0.0.1:8080",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.login()

print(client.token())
```

{% endtab %}

{% tab title="GoClient" %}

```go
import "github.com/datarhei/core-client-go/v16"

client, err := coreclient.New(coreclient.Config{
    Address: "http://127.0.0.1:8080",
    Username: "YOUR_USERNAME",
    Password: "YOUR_PASSWORD",
})
if err != nil {
    ...
}
```

By creating a new core client, the login automatically happens. If the login fails, `coreclient.New()` will return an error.
{% endtab %}
{% endtabs %}

Description:

{% openapi src="/files/AUmcih4nC1IX6QuhfO8m" path="/api/login" method="post" %}
[doc.json](https://951110271-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQRvnKSkK1SsZB0HeYhh%2Fuploads%2F3duUHhkhwH69BGLlHYga%2Fdoc.json?alt=media\&token=dcd2b063-c826-4652-9a98-c265ec41a469)
{% endopenapi %}

## Auth0 login

Send a valid Auth0 access JWT in the `Authorization` header to the `/api/login` endpoint in order to obtain an access and refresh JWT. The Auth0 tenant and the allowed users must be defined in the [configuration](https://docs.datarhei.com/core/api/pages/BVeGjgPvhjHjN3ThePBj#auth.auth0.enable-bool).

Example:

{% tabs %}
{% tab title="Curl" %}

```bash
curl http://127.0.0.1:8080/api/login \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer eyJz93a...k4laUWw' \
   -X POST
```

{% endtab %}

{% tab title="PyClient" %}

```python
from core_client import Client

client = Client(
    base_url="http://127.0.0.1:8080",
    auth0_token="eyJz93a...k4laUWw",
)
client.login()
```

{% endtab %}

{% tab title="GoClient" %}

```go
import "github.com/datarhei/core-client-go/v16"

client, err := coreclient.New(coreclient.Config{
    Address: "http://127.0.0.1:8080",
    Auth0Token: "eyJz93a...k4laUWw",
})
if err != nil {
    ...
}
```

{% endtab %}
{% endtabs %}

{% openapi src="/files/AUmcih4nC1IX6QuhfO8m" path="/api/login" method="post" %}
[doc.json](https://951110271-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQRvnKSkK1SsZB0HeYhh%2Fuploads%2F3duUHhkhwH69BGLlHYga%2Fdoc.json?alt=media\&token=dcd2b063-c826-4652-9a98-c265ec41a469)
{% endopenapi %}

## JWT refresh

In order to obtain a new access token, use the `refresh_token` for a call to `/api/login/refresh`. Example:

{% tabs %}
{% tab title="Curl" %}

```bash
curl http://127.0.0.1:8080/api/login/refresh \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGkiOjg2NDAwLCJleHAiOjE2NzA1Mjc2MjUsImlhdCI6MTY3MDQ0MTIyNSwiaXNzIjoiZGF0YXJoZWktY29yZSIsImp0aSI6IjczM2Q4Y2UxLTY3YjEtNDM3Yy04YzQ1LTM3Yjg4MmZjMWExZiIsInN1YiI6ImFkbWluIiwidXNlZm9yIjoicmVmcmVzaCJ9.3lqZFJeN7ILfM4DTi0-ZJ7kAzqTMR-yRgRl3o89O-jY' \
   -X GET
```

On successful login, the response looks like this:

```bash
{
   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGkiOjYwMCwiZXhwIjoxNjcwNDQxODI1LCJpYXQiOjE2NzA0NDEyMjUsImlzcyI6ImRhdGFyaGVpLWNvcmUiLCJqdGkiOiJhZWU4OTZhNS05ZThhLTRlMGQtYjk4Zi01NTA3NTUwNzA2YzUiLCJzdWIiOiJhZG1pbiIsInVzZWZvciI6ImFjY2VzcyJ9.xrnIfNZU9Z0nrUxYddpPQOMO7ypHA2vuqrYuAr95elg"
}
```

{% endtab %}

{% tab title="PyClient" %}
The client handles the refresh of the tokens automatically. However, the `access_token` can also be updated manually:

```python
from core_client import Client

client = Client(
    base_url="http://127.0.0.1:8080",
    refresh_token="eyJz93a...k4laUWw",
)
client.token_refresh()
```

{% endtab %}

{% tab title="GoClient" %}
The client handles the refresh of the tokens automatically. However, you can extract the currently used tokens from the client:

```go
accessToken, refreshToken := client.Tokens()
```

You can use these tokens to continue this session later on, given that at least the refresh token didn't expire yet. This saves the client a login round-trip:

```go
client, err := coreclient.New(coreclient.Config{
    Address: "http://127.0.0.1:8080",
    Username: "YOUR_USERNAME",
    Password: "YOUR_PASSWORD",
    AccessToken: accessToken,
    RefreshToken: refreshToken,
})
```

The username and password should be provided as well, in case the refresh token expires.
{% endtab %}
{% endtabs %}

Once the refresh token expires, you have to login again with your username and password, or a valid Auth0 token.

Description:

{% openapi src="/files/AUmcih4nC1IX6QuhfO8m" path="/api/login/refresh" method="get" %}
[doc.json](https://951110271-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQRvnKSkK1SsZB0HeYhh%2Fuploads%2F3duUHhkhwH69BGLlHYga%2Fdoc.json?alt=media\&token=dcd2b063-c826-4652-9a98-c265ec41a469)
{% endopenapi %}


---

# 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.datarhei.com/core/api/login.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.