Authentication

Every endpoint takes a bearer token. The DynDNS endpoint also takes HTTP Basic Auth.

Use API keys for unattended integrations

For scripts and other unattended access, use an API key instead of POST /authenticate with your password. A key has its own permissions, survives password changes and can be revoked on its own. Send it the same way as a bearer token.

Bearer token

POST /authenticate

Field	Type	Required	Description
username	string	Yes	Account email address.
password	string	Yes	Account password.
code	number	If 2FA is enabled	Current TOTP code.

curl -X POST https://api.gigahost.no/api/v0/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "your-password"
  }'

Response:

{
  "meta": { "status": 200, "status_message": "200 OK" },
  "data": {
    "token": "<long-bearer-token>",
    "token_expire": 1779843600,
    "customer_id": 12345
  }
}

token_expire is a Unix timestamp.

Use the token

Pass the token in the Authorization header:

curl https://api.gigahost.no/api/v0/servers \
  -H "Authorization: Bearer $TOKEN"

Invalidate the token

curl -X POST https://api.gigahost.no/api/v0/logout \
  -H "Authorization: Bearer $TOKEN"

HTTP Basic Auth

Accepted only on GET /dns/dyndns (the Dynamic DNS endpoint), with your account email and password. Every other endpoint answers 401 to Basic Auth. Failed attempts count towards the same limit as POST /authenticate (see Login limits).

curl -u "[email protected]:your-password" \
  "https://api.gigahost.no/api/v0/dns/dyndns?hostname=home.example.com"

Two-factor authentication (2FA)

With 2FA on, POST /authenticate needs the current TOTP code in code:

curl -X POST https://api.gigahost.no/api/v0/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "your-password",
    "code": 123456
  }'

Without the code, the request fails with 400 and need2fa: true in meta. A wrong code fails with 403 and twofactorfailed: true.

2FA is set up under Authentication.

Login limits

Failed logins are counted per UTC day. After 20 failed passwords for one username from one IP address, 200 from one IP address, or 20 wrong 2FA codes for one user, POST /authenticate answers 429 Too many failed login attempts. Please try again later. and HTTP Basic Auth answers 401 until the next day.