Authentication

Every endpoint except Authentication itself requires a JWT access token, sent on every request as:

Authorization: Bearer <accessToken>

What you'll do

Exchange your Ergani credentials for an access token (3-hour lifetime) and a refresh token (7-day lifetime). Use the access token on every request. Renew it with the refresh token before it expires — don't re-authenticate with credentials on every call.

Request

POST /Authentication
Content-Type: application/json

{
  "Username": "myusername",
  "Password": "mypassword",
  "Usertype": "02"
}

Field	Value
Username / Password	Your Ergani (e-ΕΦΚΑ) credentials.
Usertype	"02" for almost all integrations — login with Ergani credentials. See below for the other values.

Other Usertype values

Value	Meaning
01	External login
02	Login with Ergani credentials (default — use this)
03	Login for construction-project credentials via e-ΕΦΚΑ

cURL

curl -s -X POST \
  "https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication" \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "myusername",
    "Password": "mypassword",
    "Usertype": "02"
  }'

Node.js

const response = await fetch(
  "https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      Username: "myusername",
      Password: "mypassword",
      Usertype: "02",
    }),
  }
);

const auth = await response.json();
console.log(auth.accessToken);

PHP

<?php

$ch = curl_init("https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "Username" => "myusername",
    "Password" => "mypassword",
    "Usertype" => "02",
]));

$response = curl_exec($ch);
curl_close($ch);

$auth = json_decode($response, true);
echo $auth["accessToken"];

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "accessTokenExpired": 10800,
  "refreshToken": "pnFB5Vdno3pd/YgkzBjDdn+Vxe29b5I+eTLSWD8cbWk=",
  "refreshTokenExpired": "2024-05-11T09:43:37.5388855+03:00"
}

Field	Description
accessToken	Send this in Authorization: Bearer <accessToken> on every other request.
accessTokenExpired	Access token lifetime in seconds (10800 = 3 hours).
refreshToken	Use this to get a new access token without re-sending credentials — see below.
refreshTokenExpired	ISO 8601 expiry timestamp of the refresh token (7 days from issue).

Store all four values. You'll need accessToken for requests and refreshToken to renew it.

What went wrong

Response	Meaning	Fix
401 Unauthorized on Authentication	Wrong username, password, or Usertype.	Double-check credentials. Usertype is almost always "02".
429 Too Many Requests	You've called Authentication (or Refresh) too many times.	Stop re-authenticating on every request — see Reuse your tokens below.

Renewing the access token

POST /Authentication/Refresh
Content-Type: application/json

{
  "AccessToken": "<current accessToken>",
  "RefreshToken": "<current refreshToken>"
}

Returns the same shape as Authentication — a new accessToken, accessTokenExpired, refreshToken, and refreshTokenExpired.

Node.js

const response = await fetch(
  "https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication/Refresh",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      AccessToken: currentAccessToken,
      RefreshToken: currentRefreshToken,
    }),
  }
);

const refreshed = await response.json();

PHP

<?php

$ch = curl_init("https://trialv2eservices.yeka.gr/WebservicesAPI/Api/Authentication/Refresh");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "AccessToken" => $currentAccessToken,
    "RefreshToken" => $currentRefreshToken,
]));

$response = curl_exec($ch);
curl_close($ch);

$refreshed = json_decode($response, true);

Logging out

POST /Authentication/Logout
Content-Type: application/json

"43TD1+HMkakFt+uKDQoN+mKxttgHvSxN9S8AI+5e4kE="

The body is the refresh token as a bare JSON string — not an object. Logout doesn't delete the refresh token outright; it shortens its remaining lifetime to 3 hours. Returns 200 OK with no body.

Reuse your tokens — don't re-authenticate per request

This is the #1 integration mistake

Calling Authentication (or Authentication/Refresh) before every request will get you rate-limited with 429 Too Many Requests.

Do this:

authenticate once
  → store accessToken + refreshToken
  → use accessToken on every request
  → on 401 / api-token-expired:true, call Refresh once
  → retry the request with the new accessToken

Not this:

authenticate → call → authenticate → call → authenticate → call ...
authenticate → refresh → call → refresh → call → refresh → call ...

The full token lifecycle

1. Acquire: Authentication with credentials → access token (3h) + refresh token (7d).
2. Use: send Authorization: Bearer <accessToken> on every request.
3. On 401 or response header api-token-expired: true: call Authentication/Refresh with the current access + refresh tokens, then retry the original request with the new access token.
4. If Authentication/Refresh itself returns 401 (refresh token expired after 7 days): go back to step 1.

What's next

Continue to Workflows to send your first check-in.