Authentication

Scheme

The bot API uses bearer token authentication only:

Authorization: Bearer <token>

Token verification

Endpoint:

GET /bot/auth/verify

This is a small utility endpoint for checking a bot token.

It is useful to:

• quickly verify that the token is still valid
• confirm that bot auth is configured correctly
• avoid doing a test create/read
• use it in onboarding and health checks

Example curl:

curl -X GET \
  -H "Authorization: Bearer <token>" \
  https://public-api.hcapp.ee/bot/auth/verify

Successful response:

{
  "success": true,
  "error_message": null,
  "data": {
    "user_id": 38,
    "company_id": 3,
    "role": "BOT"
  }
}

If the token is invalid or expired, the API returns 401.

Token requirements

• Use a bot token issued by HCAPP
• Pass the token in Authorization: Bearer <token>
• The token has an expiration time
• The token is bound to a user with role BOT

If the token belongs to a non-bot user, the API returns HTTP 403 with Bot token required.

Access scope

• A valid bot token does not grant access to every form
• Task creation requires bot access to the target form
• Read and update endpoints check access using task.form_id

What is not included

The current bot API code does not expose a separate token-issuance endpoint.
This section documents how an already issued bot token is used.