Access the API

Loyalty Harbor exposes its services as a REST API. To access this services, you initially have to authorize to get an access token. The authorization mechanism is based on OpenID Connect. OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. As response you'll get a JWT (JSON Web Token) as access token.

Authorization

Loyalty Harbor provides two standard ways of authorization:

  • Username / Password
  • Secret Token

If you need additional kinds of authorization, please contact api@loyaltyharbor.de

Username / Password

Authorization by username and password is the preferred way to login an end customer.

curl -L -X POST 'https://localhost:8000/auth/realms/harbor/protocol/openid-connect/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=react-loyalty' \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'username=<a valid username>' \
    --data-urlencode 'password=<a valid password>'

Secret Token

Authorization by secret token is the prefered way for server to server communications.

curl -L -X POST 'https://localhost:8000/auth/realms/harbor/protocol/openid-connect/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=cashpoint' \
    --data-urlencode 'client_secret=<a valid secret>' \
    --data-urlencode 'grant_type=client_credentials'

Response

After successful authentication the client gets the following response:

{
  "access_token":"<access token>",
  "expires_in":300,
  "refresh_expires_in":1800,
  "refresh_token":"<refresh token>",
  "token_type":"bearer",
  "not-before-policy":0,
  "session_state":"31e5636e-e00f-4bc3-b538-4961b9553329",
  "scope":"profile microprofile-jwt email"
}

Use the access_token to authenticate while performing calls to protected resources.

Authentication

When a client wants to access a protected resource from the Loyalty Harbor API, the client should send the JWT. This is done in the Authorization header using the Bearer schema. This additional header might look like the following:

Authorization: Bearer <access_token>

Refresh Token

JWT Tokens are valid for limited time. If a token expires, the client have to get a new access token. In the JWT response from the authorization you can use the refresh_token to refresh the access_token.

curl -L -X POST 'https://auth.local.loyaltyharbor.de/auth/realms/harbor/protocol/openid-connect/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=react-admin' \
    --data-urlencode 'grant_type=refresh_token' \
    --data-urlencode 'refresh_token=<refresh token>'

The response is same like the response from the authorization, but with fresh tokens.