# 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/configuration/api-security#auth.username-string) and [api.auth.password](https://docs.datarhei.com/core/configuration/api-security#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="<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>" 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/configuration/api-security#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="<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>" 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="<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>" 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 %}