Authentication

#Turn off the account's two-factor authentication (admin)

DELETE/api/v1/accounts/{id}/2fa

An admin turns a customer's 2FA off (lost phone and recovery codes).

Who

root, reseller (ACL: passwd)

API tokens

API tokens can't use this endpoint

Operation

acct2FAReset · ky call acct2FAReset

Parameters

Responses

• 204 Done, no content
• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
• 404 Not Found: not-found
• 500 Internal Server Error: internal

#Two-factor authentication status

GET/api/v1/accounts/{id}/2fa

Who

root, reseller (ACL: create-user-session); customer

API tokens

API tokens can't use this endpoint

Operation

acct2FAStatus · ky call acct2FAStatus

Parameters

Responses

• 200 OK
  Body

  Field	Type
  enabled	boolean
  enabled_at	integer
  recovery_codes_left	integer

• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
• 500 Internal Server Error: internal

#Turn off two-factor authentication

POST/api/v1/accounts/{id}/2fa/disable

Who

root, reseller (ACL: create-user-session); customer

API tokens

API tokens can't use this endpoint

Operation

acct2FADisable · ky call acct2FADisable

Parameters

Request body

Responses

• 204 Done, no content
• 400 Bad Request: validation
• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: customer-only
• 429 Too Many Requests: too-many-attempts
• 500 Internal Server Error: internal

#Turn on two-factor authentication

POST/api/v1/accounts/{id}/2fa/enable

Who

root, reseller (ACL: create-user-session); customer

API tokens

API tokens can't use this endpoint

Operation

acct2FAEnable · ky call acct2FAEnable

Parameters

Request body

Responses

• 200 OK
  Body

  Field	Type
  recovery_codes	array of string

• 400 Bad Request: invalid-enroll-token, validation
• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: customer-only
• 500 Internal Server Error: internal

#Generate new recovery codes

POST/api/v1/accounts/{id}/2fa/recovery-codes

Who

root, reseller (ACL: create-user-session); customer

API tokens

API tokens can't use this endpoint

Operation

acct2FARecoveryCodes · ky call acct2FARecoveryCodes

Parameters

Request body

Responses

• 200 OK
  Body

  Field	Type
  recovery_codes	array of string

• 400 Bad Request: validation
• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: customer-only
• 409 Conflict: no-2fa
• 429 Too Many Requests: too-many-attempts
• 500 Internal Server Error: internal

#Start two-factor authentication setup

POST/api/v1/accounts/{id}/2fa/setup

Who

root, reseller (ACL: create-user-session); customer

API tokens

API tokens can't use this endpoint

Operation

acct2FASetup · ky call acct2FASetup

Parameters

Responses

• 200 OK
  Body

  Field	Type
  enroll_token	string
  otpauth_uri	string
  secret	string

• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: customer-only
• 500 Internal Server Error: internal

#Stop acting as a reseller

POST/api/v1/auth/act-as/exit

Who

public

API tokens

not needed

Operation

exitActAs · ky call exitActAs

Responses

• 200 OK
  Body

  Field	Type
  redirect	string

• 401 Unauthorized: no-session
• 403 Forbidden: csrf
• 409 Conflict: not-acting
• 500 Internal Server Error: internal

#Sign in to Ky Admin

POST/api/v1/auth/login

Who

public

API tokens

not needed

Operation

login · ky call login

Request body

Responses

• 200 OK
  Body

  Field	Type
  acl	array of string
  acting_as always	boolean
  authenticated always	boolean
  csrf_token	string
  expires_at	integer
  force_password_change always	boolean
  is_root always	boolean
  mfa_required always	boolean
  password_expired	boolean
  reseller	ResellerBrief
  role	string
  two_factor_enabled always	boolean
  two_factor_setup_required always	boolean
  username	string

• 401 Unauthorized: invalid-credentials
• 403 Forbidden: admin-ip-not-allowed, suspended
• 429 Too Many Requests: too-many-attempts
• 500 Internal Server Error: internal

#Sign out of Ky Admin

POST/api/v1/auth/logout

Who

public

API tokens

not needed

Operation

logout · ky call logout

Responses

• 204 Done, no content
• 403 Forbidden: csrf

#Ky Admin second sign-in step

POST/api/v1/auth/mfa

Who

public

API tokens

not needed

Operation

mfa · ky call mfa

Request body

Responses

• 200 OK
  Body

  Field	Type
  acl	array of string
  acting_as always	boolean
  authenticated always	boolean
  csrf_token	string
  expires_at	integer
  force_password_change always	boolean
  is_root always	boolean
  mfa_required always	boolean
  password_expired	boolean
  reseller	ResellerBrief
  role	string
  two_factor_enabled always	boolean
  two_factor_setup_required always	boolean
  username	string

• 400 Bad Request: no-2fa
• 401 Unauthorized: invalid-code, no-session
• 403 Forbidden: csrf
• 429 Too Many Requests: too-many-attempts
• 500 Internal Server Error: internal

#Ky Admin session

GET/api/v1/auth/session

Who

public

API tokens

not needed

Operation

sessionInfo · ky call sessionInfo

Responses

• 200 OK
  Body

  Field	Type
  acl	array of string
  acting_as always	boolean
  authenticated always	boolean
  csrf_token	string
  expires_at	integer
  force_password_change always	boolean
  is_root always	boolean
  mfa_required always	boolean
  password_expired	boolean
  reseller	ResellerBrief
  role	string
  two_factor_enabled always	boolean
  two_factor_setup_required always	boolean
  username	string

#Redeem a Ky Admin sign-in link

GET/api/v1/auth/sso

Redeems a Ky Admin link and opens the reseller's admin session.

Who

public

API tokens

not needed

Operation

adminSSO · ky call adminSSO

Parameters

Responses

• 302 Redirect
• 500 Internal Server Error: internal

#Turn off your two-factor authentication

POST/api/v1/me/2fa/disable

Who

root

API tokens

API tokens can't use this endpoint

Operation

twoFactorDisable · ky call twoFactorDisable

Request body

Responses

• 204 Done, no content
• 400 Bad Request: validation
• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
• 500 Internal Server Error: internal

#Turn on your two-factor authentication

POST/api/v1/me/2fa/enable

Who

root

API tokens

API tokens can't use this endpoint

Operation

twoFactorEnable · ky call twoFactorEnable

Request body

Responses

• 204 Done, no content
• 400 Bad Request: invalid-enroll-token, validation
• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
• 500 Internal Server Error: internal

#Start your two-factor authentication setup

POST/api/v1/me/2fa/setup

Who

root

API tokens

API tokens can't use this endpoint

Operation

twoFactorSetup · ky call twoFactorSetup

Responses

• 200 OK
  Body

  Field	Type
  enroll_token	string
  otpauth_uri	string
  secret	string

• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
• 500 Internal Server Error: internal

#Change your admin password

POST/api/v1/me/password

Who

root

API tokens

API tokens can't use this endpoint

Operation

changePassword · ky call changePassword

Request body

Responses

• 204 Done, no content
• 400 Bad Request: validation
• 401 Unauthorized: no session, or an invalid or expired token
• 403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
• 500 Internal Server Error: internal

#Switch from the customer panel to Ky Admin (resellers)

POST/api/v1/user/admin-link

A reseller in its customer panel switches to Ky Admin (single-use link, 60 s).

Who

public

API tokens

not needed

Operation

userAdminLink · ky call userAdminLink

Responses

• 200 OK
  Body

  Field	Type
  url	string

• 401 Unauthorized: no-session
• 403 Forbidden: csrf, impersonated, not-reseller, suspended
• 500 Internal Server Error: internal

#Sign in to the customer panel

POST/api/v1/user/auth/login

Who

public

API tokens

not needed

Operation

userLogin · ky call userLogin

Request body

Responses

• 200 OK
  Body

  Field	Type
  account	map of string
  authenticated always	boolean
  csrf_token	string
  expires_at	integer
  features	array of string
  impersonated always	boolean
  mfa_required always	boolean
  nameservers	array of string
  read_only always	boolean
  reseller always	boolean
  two_factor_setup_required always	boolean

• 401 Unauthorized: invalid-credentials
• 403 Forbidden: suspended
• 409 Conflict: not-ready
• 429 Too Many Requests: too-many-attempts
• 500 Internal Server Error: internal

#Sign out of the customer panel

POST/api/v1/user/auth/logout

Who

public

API tokens

not needed

Operation

userLogout · ky call userLogout

Responses

• 204 Done, no content
• 403 Forbidden: csrf

#Customer panel second sign-in step

POST/api/v1/user/auth/mfa

Who

public

API tokens

not needed

Operation

userMFA · ky call userMFA

Request body

Responses

• 200 OK
  Body

  Field	Type
  account	map of string
  authenticated always	boolean
  csrf_token	string
  expires_at	integer
  features	array of string
  impersonated always	boolean
  mfa_required always	boolean
  nameservers	array of string
  read_only always	boolean
  reseller always	boolean
  two_factor_setup_required always	boolean

• 401 Unauthorized: invalid-code, no-session
• 403 Forbidden: csrf
• 429 Too Many Requests: too-many-attempts
• 500 Internal Server Error: internal

#Customer panel session

GET/api/v1/user/auth/session

Who

public

API tokens

not needed

Operation

userSession · ky call userSession

Responses

• 200 OK
  Body

  Field	Type
  account	map of string
  authenticated always	boolean
  csrf_token	string
  expires_at	integer
  features	array of string
  impersonated always	boolean
  mfa_required always	boolean
  nameservers	array of string
  read_only always	boolean
  reseller always	boolean
  two_factor_setup_required always	boolean

• 500 Internal Server Error: internal

#Redeem a customer panel sign-in link

GET/api/v1/user/auth/sso

Who

public

API tokens

not needed

Operation

userSSO · ky call userSSO

Parameters

Responses

• 302 Redirect
• 500 Internal Server Error: internal