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 and api.auth.password, in the body of the request to the /api/login endpoint in order to obtain valid access and refresh JWT.

Example:

Curl

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:

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

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

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:

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.

PyClient

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())

GoClient

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.

Description:

Retrieve an access and a refresh token

post

Retrieve valid JWT access and refresh tokens to use for accessing the API. Login either by username/password or Auth0 token

Authorizations

AuthorizationstringRequired

Body

passwordstringRequired

usernamestringRequired

Responses

200

OK

application/json

access_tokenstringOptional

refresh_tokenstringOptional

400

Bad Request

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

post/api/login

POST /api/login HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "password": "text",
  "username": "text"
}

{
  "access_token": "text",
  "refresh_token": "text"
}

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.

Example:

Curl

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

PyClient

from core_client import Client

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

GoClient

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 {
    ...
}

Retrieve an access and a refresh token

post

Retrieve valid JWT access and refresh tokens to use for accessing the API. Login either by username/password or Auth0 token

Authorizations

AuthorizationstringRequired

Body

passwordstringRequired

usernamestringRequired

Responses

200

OK

application/json

access_tokenstringOptional

refresh_tokenstringOptional

400

Bad Request

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

post/api/login

POST /api/login HTTP/1.1
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "password": "text",
  "username": "text"
}

{
  "access_token": "text",
  "refresh_token": "text"
}

JWT refresh

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

Curl

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:

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

PyClient

The client handles the refresh of the tokens automatically. However, the access_token can also be updated manually:

from core_client import Client

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

GoClient

The client handles the refresh of the tokens automatically. However, you can extract the currently used tokens from the client:

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:

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.

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

Description:

Retrieve a new access token

get

Retrieve a new access token by providing the refresh token

Authorizations

AuthorizationstringRequired

Responses

200

OK

application/json

access_tokenstringOptional

500

Internal Server Error

application/json

get/api/login/refresh

GET /api/login/refresh HTTP/1.1
Authorization: YOUR_API_KEY
Accept: */*

{
  "access_token": "text"
}