KIO Link
KIO Link XC APIKIO Link API
KIO BMSHuawei BMSHuawei Alert
KIO Link XC APIKIO Link API
KIO BMSHuawei BMSHuawei Alert
  1. Auth
  • Auth
    • Overview
    • Log in
      POST
    • Send a one-time sign-in token
      POST
    • Log in with Apple
      POST
    • Validate a session token
      GET
    • Sign in with a one-time sign-in token
      POST
    • Request a password reset
      POST
    • Get the user of a password reset token
      GET
    • Reset a password
      POST
    • Submit a business registration request
      POST
    • Enable two-factor authentication
      POST
    • Confirm a two-factor login
      POST
  • Application Content
    • List application content
    • Create application content
    • Get application content by slug
    • Get application content by public id
    • Partially update application content
    • Delete application content
  • Businesses
    • Overview
    • Business Users
      • Overview
      • List business users by business
      • List a business's users
      • Create a business user
      • Get a business user
      • Update a business user
      • Upload a business user's avatar
      • Delete a business user's avatar
      • Deactivate business users
      • Search business users
      • Search a business's users
      • Send a password reset email to a business user
      • Reset a business user's daily sign-in code limits
      • Toggle a business user's two-factor authentication
      • Import business users from CSV
      • Export all business users
      • Set whether I receive releases
      • Set whether I receive alerts
      • Request the deletion of my account
    • Business Roles
      • Overview
      • List business user roles
      • Create a business user role
      • Get a business user role
      • Update a business user role
      • Delete a business user role
    • Business Permissions
      • Overview
      • List business user permissions
      • Create a business user permission
      • Delete a business user permission
    • Business Consoles
      • Overview
      • List a business's consoles
      • Create a business console
      • Delete a business console
    • Business Devices
      • Overview
      • List a business's devices
      • Search a business's devices
      • Export all business devices
      • Export my business's devices
      • Import business devices from CSV
      • Start device transfers from CSV
      • Import device statuses from CSV
      • Delete business devices
      • Change a device's owner
      • Get a business's device transfer log
    • Business Racks
      • Overview
      • Export all business racks
      • Assign a rack to a business
      • List a business's racks
      • List all business racks
      • Change a business rack's status
      • Delete business racks
      • Restore a deleted business rack
      • Import business racks from CSV
    • Business Locations
      • Overview
      • Update a business's status and datacenters
      • Migrate business locations to datacenters
      • Remove the old locations field from businesses
      • Migrate business user locations to datacenters
      • Migrate business device locations to datacenter names
    • Business Reports
      • Overview
      • Send the visits reports
      • Download a visits report
      • Set a business's report recipients
    • List businesses
    • Search businesses
    • Search businesses by name or extra data
    • Export businesses
    • Get a business
    • Create a business
    • Import businesses from CSV
    • Update a business
    • Delete a business
  • Banned Devices
    • List banned devices
    • Check if a device is risky or banned
    • Get a banned device
    • Create a banned device
    • Update a banned device
    • Delete a banned device
  • Data Centers
    • Listar data centers
    • Crear un data center
    • Actualizar un data center
    • Eliminar un data center
  • Intake Forms
    • List intake form reponses
    • Get an intake form's response
    • Get an intake form's response license file
    • Get an intake form's response identification file
    • Download intake form responses report
    • Create an intake form's response
    • Upload a license file to an intake form's response
    • Upload an identification file to an intake form's response
    • Update an intake form's response
    • Delete an intake form's response
  • Users
    • Overview
    • Permissions
      • Overview
      • Generate KIO user permissions
      • Generate business user permissions
      • List KIO user permissions
      • Create a KIO user permission
      • Delete a KIO user permission
    • Roles
      • Overview
      • List KIO user roles
      • Create a KIO user role
      • Get a KIO user role
      • Update a KIO user role
      • Delete a KIO user role
    • User Groups
      • Overview
      • List user groups
      • Create a user group
      • Update a user group
      • Delete a user group
    • List KIO users
    • Create a KIO user
    • Get a KIO user
    • Update a KIO user
    • Activate or deactivate a KIO user
    • Delete a KIO user
    • Generate a session token for a user
    • Export KIO users
    • Search active KIO users by name
    • Search KIO users
    • Look up an employee in SuccessFactors
    • Import KIO user updates from CSV
  • External Users
    • Overview
    • List external users
    • Find external users to invite
    • Search external users
    • Export external users
    • Create an external user
    • Edit an external user
    • Update an external user
    • Upload an external user's avatar
    • Delete an external user's avatar
    • Delete an external user
  • Send App Notification
    POST
  • Events Locations
    GET
  • Fetch Wires
    GET
  • Create Business Temporary Secret
    POST
  • Schemas
    • Auth
      • Auth Session
      • Two-Factor Status
      • Two-Factor Challenge
      • KIO User Session
    • Businesses
      • Business Users
        • Business User Role
        • Datacenter Access
        • Business User
        • Business User With Relations
        • Business User Permission
      • Business Devices
        • Business Device
        • Business Device Log Entry
      • Business Racks
        • Business Rack
        • Datacenter Rack
      • Business
      • Datacenter Assignment
      • Business List Item
      • Business Console
    • Users
      • User Role
      • User
      • User Permission
      • User Group
      • Permission Catalog
      • SuccessFactors Employee
    • External Users
      • External User
    • ApplicationContentCreate
    • ApplicationContentUpdate
    • ApplicationContent
    • ApplicationContentListResponse
    • Banned Device
    • Error
    • LanguageEntry
    • Pagination
    • Intake Form
    • DataCenter
    • LocalizedContent
    • Delete Result
    • Import Row Error
    • Bulk Write Result
    • Message
    • Personal Device
  1. Auth

Overview

Auth#

Sign-in, session validation, one-time sign-in tokens, password resets and two-factor authentication. Every endpoint in this folder is public: none requires an Authorization token.

Concepts#

Two kinds of users:
Business users are client-side users that belong to a business. They sign in with email and password, or with a one-time sign-in (OTS) token sent by email.
KIO users are internal employees. They sign in with Google (token in Log in) or with Apple.
Session token: every successful sign-in returns a JWT in token and the user's permission slugs in permissions. Send the token in the Authorization header (Bearer <token> or the raw token) on authenticated endpoints. It is valid for 30 days, except tokens issued with an OTS token, which are valid for 24 hours.
Two-factor authentication (2FA) applies only to business users signing in with a password, unless 2FA is disabled for the user (two_factor_auth_unavailable):
On the first sign-in, a grace period starts (TWO_FA_GRACE_DAYS, default 30 days). While it lasts, Log in returns the session directly.
Once it ends, Log in returns HTTP 202 and emails a 6-character code. Finish with Confirm a two-factor login.
Every confirmed 2FA code or OTS sign-in starts a new grace period.
Codes can be requested once every OTS_TWO_FA_COOLDOWN_SECONDS (default 120 s), up to OTS_TWO_FA_DAILY_LIMIT (default 8) per day.
One-time sign-in (OTS) tokens: a passwordless sign-in for business users. Tokens are 6 characters, expire after 5 minutes, can be requested once every 2 minutes, and are limited to 6 requests or sign-ins per user per day.
Password resets: the reset email carries a token valid for 24 hours. New passwords need at least 8 characters with an uppercase letter, a lowercase letter, a digit and a special character, and expire after 90 days.
Errors with HTTP 200: some failures are returned with status 200 and an Error body: Google sign-in rejections in Log in, invalid tokens in Reset a password, and invalid sessions in Validate a session token (valid: false).

Endpoints#

Log in#

POST /v1/auth/login
Signs in a business user with email and password (with 2FA), or a KIO user with Google.

Log in with Apple#

POST /v1/auth/apple-login
Signs in a KIO user with Sign in with Apple.

Confirm a two-factor login#

POST /v1/auth/confirm-login-2fa
Finishes a password sign-in with the emailed 2FA code.

Enable two-factor authentication#

POST /v1/auth/enable-two-factor-auth
Activates 2FA for a business user and starts a new grace period.

Validate a session token#

GET /v1/auth/validate-token
Checks a session token and returns its owner.

Send a one-time sign-in token#

POST /v1/auth/generate-ots-token
Emails an OTS token to a business user.

Sign in with a one-time sign-in token#

POST /v1/auth/validate-ots-token
Exchanges an OTS token for a 24-hour session.

Request a password reset#

POST /v1/auth/forgot-password-request
Emails a password reset link to a business user.

Get the user of a password reset token#

GET /v1/auth/reset-password-request/{token}
Validates a reset token and returns its user.

Reset a password#

POST /v1/auth/reset-password
Sets a new password with a reset token.

Submit a business registration request#

POST /v1/auth/business-register-request
Placeholder; echoes the request body.

Source#

Router: routes/v1/auth.js
Controller: controllers/auth.js
Services: services/jwt.js, services/auth-apple.js, services/mailing.js
Models: models/business_user.js, models/business_user_access_token.js, models/user.js
Email templates: generate-token, ots-token-limit, resetPassword
Modified at 2026-10-05 19:51:57
Next
Log in
Built with