Authentication

Every request to the API needs an OAuth2 access token. A system that calls the API on its own, without a person logging in, gets that token with an API key and the client credentials grant.

API keys

An API key is a machine client of your tenant. It has a client ID, a client secret and a set of permissions, and it holds those permissions the same way a user does. An API key never expires on its own.

Create an API key

Tenant administrators create API keys themselves:

Open HuskyCare and go to Benutzerverwaltung → API-Keys. The tab is only visible to tenant administrators.
Create a key. Give it a name and, optionally, a description of what uses it.
Choose the permissions. A key holds either role templates in individual residential parks, or role templates in every park of the tenant, including parks created later. With several role templates, the key gets all features of all of them.
Copy the client secret from the dialog. HuskyCare shows it once and stores no copy you can read later.

The client ID has the form apikey-<name>-<random suffix> and is shown in the API key list.

You can also manage API keys through the API with createApiKey and the related operations. They require the features api_key:core:create, api_key:core:read and api_key:core:manage, which only tenant administrators hold.

Grant a key only the role templates its integration needs. Each operation in the API reference lists the authorization features it requires, and the authorization overview lists them by feature.

Manage an API key

Action	Effect
Change permissions	Replaces the key's permissions. Tokens requested afterwards carry the new permissions.
Rotate secret	Issues a new client secret. The old secret stops working immediately.
Disable	The key can no longer request tokens. Enable it again to restore access with the same secret and permissions.
Delete	Removes the key permanently.

A token that was issued before you disabled or deleted the key stays valid until it expires, which takes at most a few minutes. If a secret has leaked, rotate or delete the key, and treat the following minutes as still exposed.

A lost secret cannot be recovered. Rotate the key to get a new one.

Request a token

Send the client ID and secret to the token endpoint of your tenant with grant_type=client_credentials:

curl -X POST \
  'https://login.huskycare.eu/realms/<tenant>/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<client id>' \
  -d 'client_secret=<client secret>'

Replace <tenant> with your tenant name. For the reference environment, the endpoint is https://login.huskycare.dev/realms/main/protocol/openid-connect/token. See Environments.

The response contains the token and its lifetime in seconds:

{
  "access_token": "<access token>",
  "expires_in": 300,
  "token_type": "Bearer"
}

Tokens are short-lived. Cache the token, and request a new one with the same call shortly before expires_in has passed. The client credentials grant has no refresh token.

Send the token

Put the token in the Authorization header of every API request:

Authorization: Bearer <access token>

A request without a valid token is rejected with HTTP 401 before the API processes it. A valid token that lacks a feature the operation requires produces a GraphQL error with the code AUTHORIZATION_DENIED_MISSING_FEATURES. See Errors.

API Playground

The API Playground is a GraphiQL interface on the reference environment. It asks you to log in with a HuskyCare user account and then sends requests with that user's permissions. Use it to try queries before you build them into your client.

API keys​

Create an API key​

Manage an API key​

Request a token​

Send the token​