IAM API

Overview

This page documents the Identity and Access Management (IAM) APIs for kis.ai, providing comprehensive endpoints for authentication, authorization, user management, and administrative operations.

Health & Status Endpoints

Health

GET /iam/health - Get health status of the server

Response Example:

{
    "healthy": true,
    "dependencies": {},
    "memstats": {
        "Alloc": 7,
        "HeapAlloc": 7,
        "HeapSys": 19,
        "HeapIdle": 8,
        "HeapInUse": 10,
        "TotalAlloc": 60224,
        "Sys": 27,
        "NumGC": 1265
    },
    "version": ""
}

Ready

GET /iam/ready - Get ready status of the server

Response:

ready: true

Realm & Provider Endpoints

List Realms

GET /account/auth/realms - Lists all realms of this product

Response:

{
    "default": "users",
    "realms": ["users"]
}

List Auth Providers

GET /account/auth/providers - Lists all auth providers

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Response:

{
    "providers": [
        {
            "method": "post",
            "name": "password",
            "type": "challenge",
            "url": "/auth/login/password"
        }
    ]
}

Authentication Endpoints

POST /account/auth/login/password - Log in with password as a challenge

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "password": "strongpassword"
}

Response:

{
    "refresh": "<refreshtoken to be substituted>",
    "token": "<token to be substituted>"
}

POST /account/auth/login/adminfederation - Federation log in

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "password": "strongpassword"
}

Response:

{
    "refresh": "<refreshtoken to be substituted>",
    "token": "<token to be substituted>"
}

POST /account/auth/login/password - Mobile log in

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "mobile": "1041917",
    "password": "strongpassword"
}

Response:

{
    "refresh": "refreshtoken to be substituted",
    "token": "token to be substituted"
}

OTP (One-Time Password) Endpoints

POST /account/auth/login/otpemail - OTP log in

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]"
}

Response:

{
    "message": "otp generated successfully"
}

POST /account/auth/login/otp02 - OTP log in

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "otp": "something"
}

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

POST /account/auth/login/passwordotp - Password login with OTP MFA

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "password": "something"
}

Response:

{
    "message": "mfa is required"
}

POST /account/auth/login/passwordotp - Approve login with OTP MFA

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "password": "something",
    "otp": "otp"
}

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

TOTP (Time-based OTP) Endpoints

POST /account/auth/login/passwordtotp - Password login with TOTP MFA (Currently Unsupported MFA Type)

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "password": "something"
}

Response:

{
    "message": "mfa is required"
}

Approve MFA TOTP Request

POST /account/auth/login/passwordtotp - Approve TOTP MFA login (Currently Unsupported MFA Type)

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "password": "something",
    "totp": "otp"
}

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

HOTP (HMAC-based OTP) Endpoints

POST /account/auth/login/passwordhotp - Password login with HOTP MFA (Currently Unsupported MFA Type)

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "password": "something"
}

Response:

{
    "message": "mfa is required"
}

Approve MFA HOTP Request

POST /account/auth/login/passwordhotp - Approve HOTP MFA request (Currently Unsupported MFA Type)

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "hotp": "otp"
}

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

WebAuthn Endpoints

POST /account/auth/login/passwordwebauthn - Password login with WebAuthn MFA (Currently Unsupported MFA Type)

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "password": "something"
}

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

POST /account/auth/webauthn/login/begin/:provider - WebAuthn login begin

Query Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

URL Parameters:

Name	Type	Data Type	Description
provider	required	string	Specifies the provider

Request:

{
    "email": "[email protected]",
    "password": "something"
}

Response: Contains a cookie and a body:

{
    "publicKey": "<webauthn public key>"
}

POST /account/auth/webauthn/login/finish/:provider - WebAuthn login finish

Query Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

URL Parameters:

Name	Type	Data Type	Description
provider	required	string	Specifies the provider

Request:

{
    "email": "[email protected]",
    "password": "something"
}

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

Webauthn Register Begin

GET /account/auth/webauthn/register/begin/:provider - WebAuthn register begin

Parameters:

Name	Type	Data Type	Description
provider	required	string	Specifies the provider

Response: Contains a cookie and a body:

{
    "publicKey": "<webauthn public key>"
}

Webauthn Register Finish

POST /account/auth/webauthn/register/finish/:provider - WebAuthn register finish

Parameters:

Name	Type	Data Type	Description
provider	required	string	Specifies the provider

Query Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "id": "string",
    "type": "string",
    "rawID": "base64",
    "clientExtensionResults": {},
    "response": {
        "clientDataJSON": "base64",
        "attestationObject": "base64"
    },
    "transports": ["strings"]
}

Response: Contains a cookie and a body:

{
    "message": "webauthn registration successful"
}

Magic Link Endpoints

POST /account/auth/login/magic02 - Create magic link login

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]"
}

Response:

{
    "massage": "magic link generated successfully",
    "tokenid": "<token to be substituted>"
}

GET /account/auth/login/magic02 - Magic link login method

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm
token	required	string	Token contains the key to obtain the auth token

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

POST /account/auth/check/approval/magic02 - Login with the given token

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "tokenid": "01G4KPR196C8R210MZXHZNZRAK"
}

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

Magic Numbers Endpoints

POST /account/auth/login/magicnumbers - Create login with magic numbers

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]"
}

Response: TokenID is not present in the response if remotelogin is set to false:

{
    "message": "magic link generated successfully",
    "tokenid": "id of the user_magic_link created",
    "number": "chosen number"
}

POST /account/auth/login/magicnumbers - Login with the given magic numbers

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm
token	required	string	Token used to login
number	required	string	Magic number required to provide in the request to login

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

POST /account/auth/check/approval/magicnumbers - Login with provided token

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "tokenid": "<token to be substituted>"
}

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

Token Management Endpoints

Refresh JWT Token

POST /account/auth/jwt/refresh - Refresh the token

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "token": "<token to be substituted>"
}

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

GET /account/auth/kisai/approve - Kisai auth login

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

OAuth Callback Provider

GET /account/auth/callback/:provider - OAuth Callback

Parameters:

Name	Type	Data Type	Description
provider	required	string	Specifies the provider

Response:

{
    "token": "<token to be substituted>",
    "refresh": "<refresh to be substituted>"
}

MFA Validation Endpoints

Check MFA TOTP Request

POST /account/auth/check/mfa/passwordtotp - Check TOTP login validity

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "name": "nameregistered",
    "totp": "559202"
}

Response:

{
    "message": "totp is valid"
}

Check MFA HOTP Request

POST /account/auth/check/mfa/passwordhotp - Check HOTP login validity

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "hotp": "123123"
}

Response:

{
    "message": "hotp is valid"
}

Password Management Endpoints

User Password Reset Request

POST /account/user/resetrequest - User password reset request

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]"
}

Response:

{
    "message": "reset request generated successfully and sent to email"
}

User Validate Token Password Request

GET /account/user/validatetoken/:resettoken/:email - Validate token password request

URL Parameters:

Name	Type	Data Type	Description
resettoken	required	string	Token received for the reset request
email	required	string	Email for which password reset was requested

Query Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]"
}

Response:

{
    "message": "token is valid"
}

User Password Reset Using Token Request

POST /account/user/resetpasswordwithtoken - User password reset link

Query Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "email": "[email protected]",
    "token": "<token>",
    "password": "<new password>"
}

Response:

{
    "message": "password reset successful"
}

User Update Password

POST /account/auth/updatepassword - Update password

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "currentpassword": "<current password>",
    "password": "<new password>"
}

Response:

{
    "message": "password update successful"
}

MFA Provider Management Endpoints

User Add TOTP MFA Provider

POST /account/auth/add/mfa/passwordtotp - Add TOTP to logged in user

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "name": "device01"
}

Response:

{
    "message": "totp mfa registered successfully",
    "uri": "<totpUri>"
}

User Add HOTP MFA Provider

POST /account/auth/add/mfa/passwordhotp - Add HOTP to logged in user

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "name": "device01"
}

Response:

{
    "message": "hotp mfa registered successfully",
    "uri": "<hotpUri>"
}

User Remove TOTP/HOTP/WebAuthn MFA Provider

POST /account/auth/remove/mfa/passwordtotp - Remove MFA for account

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Response:

{
    "message": "mfa removed successfully"
}

API Key Management Endpoints

API Key With Expiry and Capabilities

POST /account/auth/apikey - Add API key to a service

Request:

{
    "service": "<service to add the api key to>",
    "expiry": 30,
    "capabilities": {
        "read": "allow"
    }
}

Response:

{
    "capabilities": {
        "read": "allow"
    },
    "createdby": "<email logged in with>",
    "createdon": "<timestamp>",
    "deletedby": null,
    "deletedon": null,
    "expiresat": "<expiry timestamp>",
    "id": "<id>",
    "key": "<base64 encoded key>",
    "secret": "<base64 encoded secret>",
    "service": "<service this api key is valid at>",
    "updatedby": "<email logged in with>",
    "updatedon": "<timestamp>"
}

API Keys by Service Name

GET /account/auth/apikey - List API keys to a service

Parameters:

Name	Type	Data Type	Description
service	required	string	Selects the service to list the API keys for

Response:

{
    "apikeys": [
        {
            "capabilities": {
                "read": "allow"
            },
            "createdby": "<email logged in with>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "expiresat": "<expiry timestamp>",
            "id": "<id>",
            "key": "<base64 encoded key>",
            "secret": "<base64 encoded secret>",
            "service": "<service this api key is valid at>",
            "updatedby": "<email logged in with>",
            "updatedon": "<timestamp>"
        }
    ]
}

API Keys by ID

GET /account/auth/apikey - List API keys by ID

Parameters:

Name	Type	Data Type	Description
id	required	string	Selects the API key to return by its id

Response:

{
    "apikeys": {
        "capabilities": {
            "read": "allow"
        },
        "createdby": "<email logged in with>",
        "createdon": "<timestamp>",
        "deletedby": null,
        "deletedon": null,
        "expiresat": "<expiry timestamp>",
        "id": "<id>",
        "key": "<base64 encoded key>",
        "secret": "<base64 encoded secret>",
        "service": "<service this api key is valid at>",
        "updatedby": "<email logged in with>",
        "updatedon": "<timestamp>"
    }
}

Admin User Management Endpoints

Admin Create User

POST /account/admin/user - Create a user to the realm

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "firstname": "<first name>",
    "middlename": "<middle name>",
    "lastname": "<last name>",
    "email": "<email>",
    "active": true,
    "additional fields": "defined in the realm"
}

Response:

{
    "data": {
        "users": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "displayname": "<display name>",
            "email": "<user's email>",
            "firstname": "<first name>",
            "id": "<id>",
            "lastname": "<last name>",
            "locked": false,
            "meta": {},
            "middlename": "<middle name>",
            "mobile": null,
            "properties": {},
            "tags": null,
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1
        }
    }
}

Admin Update User

PUT /account/admin/user - Update the details of the user with id

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Request:

{
    "id": "<user's id>",
    "<key to change>": "<new value>"
}

Response:

{
    "data": {
        "users": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "displayname": "<display name>",
            "email": "<user's email>",
            "firstname": "<first name>",
            "id": "<id>",
            "lastname": "<last name>",
            "locked": false,
            "meta": {},
            "middlename": "<middle name>",
            "mobile": null,
            "properties": {},
            "tags": null,
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Get User by Email

GET /account/admin/user/email/:useremail - Get user details by the email

URL Parameters:

Name	Type	Data Type	Description
useremail	required	string	Email of the user to get

Query Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Response:

{
    "data": {
        "users": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "displayname": "<display name>",
            "email": "<user's email>",
            "firstname": "<first name>",
            "id": "<id>",
            "lastname": "<last name>",
            "locked": false,
            "meta": {},
            "middlename": "<middle name>",
            "mobile": null,
            "properties": {},
            "tags": null,
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Get User by ID

GET /account/admin/user/id/:id - Get user details by the id

URL Parameters:

Name	Type	Data Type	Description
id	required	string	ID of the user to get

Query Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Response:

{
    "data": {
        "users": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "displayname": "<display name>",
            "email": "<user's email>",
            "firstname": "<first name>",
            "id": "<id>",
            "lastname": "<last name>",
            "locked": false,
            "meta": {},
            "middlename": "<middle name>",
            "mobile": null,
            "properties": {},
            "tags": null,
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Delete User by ID

DELETE /account/admin/user/id/:id - Delete user by the id

URL Parameters:

Name	Type	Data Type	Description
id	required	string	ID of the user to delete

Query Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Response:

user deleted

Admin List Users

GET /account/admin/users - List the users in the realm

Parameters:

Name	Type	Data Type	Description
version	optional	integer	Specifies the version of the user object to get
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Response:

{
    "data": {
        "users": [
            {
                "active": true,
                "createdby": "<admin email>",
                "createdon": "<timestamp>",
                "deletedby": null,
                "deletedon": null,
                "displayname": "<display name>",
                "email": "<user's email>",
                "firstname": "<first name>",
                "id": "<id>",
                "lastname": "<last name>",
                "locked": false,
                "meta": {},
                "middlename": "<middle name>",
                "mobile": null,
                "properties": {},
                "tags": null,
                "updatedby": "<admin email>",
                "updatedon": "<timestamp>",
                "version": 2
            }
        ]
    }
}

Admin Lock User by Email

GET /account/admin/user/lock - Lock the user

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm
email	optional	string	Specifies the email to be locked

Response:

{
    "data": {
        "users": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "displayname": "<display name>",
            "email": "<user's email>",
            "firstname": "<first name>",
            "id": "<id>",
            "lastname": "<last name>",
            "locked": true,
            "meta": {},
            "middlename": "<middle name>",
            "mobile": null,
            "properties": {},
            "tags": null,
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1
        }
    }
}

Admin Unlock User by Email

GET /account/admin/user/unlock - Unlock the user

Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm
email	optional	string	Specifies the email to be unlocked

Response:

{
    "data": {
        "users": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "displayname": "<display name>",
            "email": "<user's email>",
            "firstname": "<first name>",
            "id": "<id>",
            "lastname": "<last name>",
            "locked": false,
            "meta": {},
            "middlename": "<middle name>",
            "mobile": null,
            "properties": {},
            "tags": null,
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1
        }
    }
}

Admin Tenant Management Endpoints

Admin Create Tenant

POST /account/admin/tenant - Create a tenant

Request:

{
    "slug": "lq",
    "displayname": "lq-admin",
    "namespace": "kisai",
    "domain": "kisai.io",
    "active": true
}

Response:

{
    "data": {
        "tenant": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "id": "<id>",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1,
            "slug": "lq",
            "displayname": "lq-admin",
            "namespace": "kisai",
            "domain": "kisai.io",
            "properties": {},
            "active": true
        }
    }
}

Admin Update Tenant

PUT /account/admin/tenant - Update a tenant

Request:

{
    "slug": "lq",
    "active": false
}

Response:

{
    "data": {
        "tenant": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "id": "<id>",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1,
            "slug": "lq",
            "displayname": "lq-admin",
            "namespace": "kisai",
            "domain": "kisai.io",
            "properties": {},
            "active": false
        }
    }
}

Admin Get Tenant by Slug

GET /account/admin/tenant/slug/:slug - Get a tenant by slug

Parameters:

Name	Type	Data Type	Description
slug	required	string	Select the tenant to return based on slug

Response:

{
    "data": {
        "tenant": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "id": "<id>",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1,
            "slug": "lq",
            "displayname": "lq-admin",
            "namespace": "kisai",
            "domain": "kisai.io",
            "properties": {},
            "active": false
        }
    }
}

Admin Get Tenants

GET /account/admin/tenant - Get tenants

Response:

{
    "data": {
        "tenant": [
            {
                "active": true,
                "createdby": "<admin email>",
                "createdon": "<timestamp>",
                "deletedby": null,
                "deletedon": null,
                "id": "<id>",
                "updatedby": "<admin email>",
                "updatedon": "<timestamp>",
                "version": 1,
                "slug": "lq",
                "displayname": "lq-admin",
                "namespace": "kisai",
                "domain": "kisai.io",
                "properties": {},
                "active": false
            }
        ]
    }
}

Admin Delete Tenant by Slug

DELETE /account/admin/tenant/slug/:slug - Delete a tenant by slug

Parameters:

Name	Type	Data Type	Description
slug	required	string	Select the tenant to delete based on slug

Response:

{
    "data": {
        "tenant": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": "<admin email>",
            "deletedon": "<timestamp>",
            "id": "<id>",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1,
            "slug": "lq",
            "displayname": "lq-admin",
            "namespace": "kisai",
            "domain": "kisai.io",
            "properties": {},
            "active": false
        }
    }
}

Admin Role Management Endpoints

Admin Create Role

POST /account/admin/role - Create a role

Request:

{
    "displayname": "dev3",
    "slug": "dev3",
    "active": true
}

Response:

{
    "data": {
        "role": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": "<admin email>",
            "deletedon": "<timestamp>",
            "displayname": "dev3",
            "id": "<id>",
            "properties": {},
            "slug": "dev3",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1
        }
    }
}

Admin Update Role

PUT /account/admin/role - Update a role

Request:

{
    "id": "<id>",
    "active": false
}

Response:

{
    "data": {
        "role": {
            "active": false,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": "<admin email>",
            "deletedon": "<timestamp>",
            "displayname": "dev3",
            "id": "<id>",
            "properties": {},
            "slug": "dev3",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Get Role by Slug

GET /account/admin/role/:slug - Get a role by slug

URL Parameters:

Name	Type	Data Type	Description
slug	required	string	Select the role to get based on slug

Response:

{
    "data": {
        "role": {
            "active": false,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": "<admin email>",
            "deletedon": "<timestamp>",
            "displayname": "dev3",
            "id": "<id>",
            "properties": {},
            "slug": "dev3",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Get Roles

GET /account/admin/role - Get all roles

Response:

{
    "data": {
        "role": [
            {
                "active": false,
                "createdby": "<admin email>",
                "createdon": "<timestamp>",
                "deletedby": "<admin email>",
                "deletedon": "<timestamp>",
                "displayname": "dev3",
                "id": "<id>",
                "properties": {},
                "slug": "dev3",
                "updatedby": "<admin email>",
                "updatedon": "<timestamp>",
                "version": 2
            }
        ]
    }
}

Admin Delete Role by Slug

DELETE /account/admin/role/:slug - Delete a role by slug

URL Parameters:

Name	Type	Data Type	Description
slug	required	string	Select the role to delete based on slug

Response:

{
    "data": {
        "role": {
            "active": false,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": "<admin email>",
            "deletedon": "<timestamp>",
            "displayname": "dev3",
            "id": "<id>",
            "properties": {},
            "slug": "dev3",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Tenant & Role User Management Endpoints

Admin Get Users for Tenant

GET /account/admin/tenant/slug/:slug/users - Get user details by the tenant slug

URL Parameters:

Name	Type	Data Type	Description
slug	required	string	Select the tenant to get users based on slug

Response:

{
    "data": {
        "users": [
            {
                "active": true,
                "createdby": "<admin email>",
                "createdon": "<timestamp>",
                "deletedby": null,
                "deletedon": null,
                "displayname": "<display name>",
                "email": "<user's email>",
                "firstname": "<first name>",
                "id": "<id>",
                "lastname": "<last name>",
                "locked": false,
                "meta": {},
                "middlename": "<middle name>",
                "mobile": null,
                "properties": {},
                "tags": null,
                "updatedby": "<admin email>",
                "updatedon": "<timestamp>",
                "version": 2
            }
        ]
    }
}

Admin Add Role to User

POST /account/admin/role/add/user - Add role to user

Request:

{
    "email": "[email protected]",
    "role": "dev2",
    "starttime": "2019-08-26T08:00:05Z"
}

Response:

{
    "data": {
        "users": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "displayname": "<display name>",
            "email": "<user's email>",
            "firstname": "<first name>",
            "id": "<id>",
            "lastname": "<last name>",
            "locked": false,
            "meta": {},
            "middlename": "<middle name>",
            "mobile": null,
            "properties": {
                "roles": [
                    {
                        "name": "dev2"
                    }
                ]
            },
            "tags": null,
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Remove Role From User

POST /account/admin/role/remove/user - Remove role from user

Request:

{
    "email": "[email protected]",
    "role": "dev2"
}

Response:

{
    "data": {
        "users": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "displayname": "<display name>",
            "email": "<user's email>",
            "firstname": "<first name>",
            "id": "<id>",
            "lastname": "<last name>",
            "locked": false,
            "meta": {},
            "middlename": "<middle name>",
            "mobile": null,
            "properties": {},
            "tags": null,
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Get Users for Role

GET /account/admin/role/slug/:slug/users - Get users for role

URL Parameters:

Name	Type	Data Type	Description
slug	required	string	Role’s slug

Response:

{
    "data": {
        "users": [
            {
                "active": true,
                "createdby": "<admin email>",
                "createdon": "<timestamp>",
                "deletedby": null,
                "deletedon": null,
                "displayname": "<display name>",
                "email": "<user's email>",
                "firstname": "<first name>",
                "id": "<id>",
                "lastname": "<last name>",
                "locked": false,
                "meta": {},
                "middlename": "<middle name>",
                "mobile": null,
                "properties": {
                    "roles": [
                        {
                            "name": "dev2"
                        }
                    ]
                },
                "tags": null,
                "updatedby": "<admin email>",
                "updatedon": "<timestamp>",
                "version": 2
            }
        ]
    }
}

Admin Realm Management Endpoints

Admin Create Realm

POST /account/admin/realm - Create a realm

Request:

{
    "name": "users",
    "realmtype": "default",
    "properties": {}
}

Response:

{
    "data": {
        "realm": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "name": "users",
            "realmtype": "default",
            "properties": {},
            "id": "<id>",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1
        }
    }
}

Admin Get Realm by ID

GET /account/admin/realm/:id - Get realm by id

URL Parameters:

Name	Type	Data Type	Description
id	required	string	Realm id

Response:

{
    "data": {
        "realm": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "name": "users",
            "realmtype": "default",
            "properties": {},
            "id": "<id>",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 1
        }
    }
}

Admin Update Realm

PUT /account/admin/realm - Update realm

Request:

{
    "id": "<id of the realm>",
    "name": "users2",
    "<key to change>": "<value to change>"
}

Response:

{
    "data": {
        "realm": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "name": "users2",
            "realmtype": "default",
            "properties": {},
            "id": "<id>",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Delete Realm by ID

DELETE /account/admin/realm/:id - Delete realm by ID

URL Parameters:

Name	Type	Data Type	Description
id	required	string	Realm id

Response:

{
    "data": {
        "realm": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": "<admin email>",
            "deletedon": "<timestamp>",
            "name": "users2",
            "properties": {},
            "realm_history": null,
            "realmtype": "default",
            "id": "<id>",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

Admin Get Realms

GET /account/admin/realm - Get all realms

Response:

{
    "data": {
        "realm": {
            "active": true,
            "createdby": "<admin email>",
            "createdon": "<timestamp>",
            "deletedby": null,
            "deletedon": null,
            "name": "users",
            "realmtype": "default",
            "properties": {},
            "id": "<id>",
            "updatedby": "<admin email>",
            "updatedon": "<timestamp>",
            "version": 2
        }
    }
}

User Session & Validation Endpoints

Index IAM Users

POST /account/index/users - Reindex IAM users

Response:

re-indexed successfully

User Validate JWT Token

GET /account/auth/validate - User validate JWT token

Response:

{
    "user": {
        "aud": "janus",
        "cluster": "dev01-forge-cluster-01-nikithenv01",
        "customer": "tenb",
        "dc": "dev01-forge-01",
        "env": "nikithenv01",
        "exp": 1697399734,
        "flowtype": "normal",
        "iat": 1697393734,
        "product": "surveyapp",
        "realm": "users",
        "roles": "",
        "tenant": "nineb",
        "ulid": "01HCT8SWSVR2NB0DG4EFW33K32",
        "user": "<email>",
        "userdisplayname": "admin ",
        "useremail": "<email>",
        "userfullname": " ",
        "userid": "01GGCG5ZPVXWA17JFGTS1HD03F",
        "useridentity": "email"
    }
}

User Auth Refresh Session

GET /account/auth/session/refresh - User auth refresh session

Query Parameters:

Name	Type	Data Type	Description
refreshtoken	required	boolean	Refresh the token

Response:

{
    "user": {
        "aud": "janus",
        "cluster": "dev01-forge-cluster-01-nikithenv01",
        "customer": "tenb",
        "dc": "dev01-forge-01",
        "env": "nikithenv01",
        "exp": 1697399734,
        "flowtype": "normal",
        "iat": 1697393734,
        "product": "surveyapp",
        "realm": "users",
        "roles": "",
        "tenant": "nineb",
        "ulid": "01HCT8SWSVR2NB0DG4EFW33K32",
        "user": "<email>",
        "userdisplayname": "admin ",
        "useremail": "<email>",
        "userfullname": " ",
        "userid": "01GGCG5ZPVXWA17JFGTS1HD03F",
        "useridentity": "email"
    }
}

Get User Preferences

POST /account/user/preferences/notification - Get user preferences

Query Parameters:

Name	Type	Data Type	Description
realm	optional	string	Specifies the realm to operate on; defaults to default realm

Response:

{
    "user": {
        "firstname": "<firstname>",
        "lastname": "<lastname>",
        "email": "<email>",
        "mobile": "<mobile>",
        "preferences": {}
    }
}

Authorization & Logout Endpoints

Execute Authorize Rule

POST /account/authorize - Execute authorize rule

Request:

{
    "module": "/iam/access",
    "rule": "admin",
    "payload": {}
}

Response:

{
    "result": ["true"]
}

User Logout

GET /account/auth/logout - User logout

Response:

{
    "status": "success",
    "message": "logged out"
}

Admin Get All User Tags

GET /account/admin/user/tag/:name - Get users with tag

URL Parameters:

Name	Type	Data Type	Description
name	required	string	Name of the tag

Response:

{
    "data": {
        "users": [
            {
                "active": true,
                "createdby": "<admin email>",
                "createdon": "<timestamp>",
                "deletedby": null,
                "deletedon": null,
                "displayname": "<display name>",
                "email": "<user's email>",
                "firstname": "<first name>",
                "id": "<id>",
                "lastname": "<last name>",
                "locked": false,
                "meta": {},
                "middlename": "<middle name>",
                "mobile": null,
                "properties": {},
                "tags": ["<name>"],
                "updatedby": "<admin email>",
                "updatedon": "<timestamp>",
                "version": 2
            }
        ]
    }
}

User Profile Endpoints

POST /account/user/signup - New user signup

Example Request:

{
    "firstname": "Firstname",
    "middlename": "",
    "lastname": "Lastname",
    "email": "[email protected]",
    "active": true
}

Example Response:

{
    "data": {
        "users": {
            "active": true,
            "createdby": "anonymous",
            "createdon": "2023-10-30T14:52:13+04:00",
            "deletedby": null,
            "deletedon": null,
            "displayname": "Firstname   Lastname",
            "email": "[email protected]",
            "firstname": "Firstname",
            "id": "01HE03CW81XC3D0WZR9SPNKX0E",
            "lastname": "Lastname",
            "locked": false,
            "meta": {},
            "middlename": "",
            "mobile": null,
            "password": null,
            "properties": {},
            "tags": null,
            "updatedby": "anonymous",
            "updatedon": "2023-10-30T14:52:13+04:00",
            "version": 1
        }
    }
}

List Other Users

GET /account/user/list - List all users

Example Response:

{
    "data": {
        "users": [
            {
                "displayname": "admin ",
                "email": "[email protected]",
                "id": "01GGCG5ZPVXWA17JFGTS1HD03F"
            },
            {
                "displayname": "name  name",
                "email": "[email protected]",
                "id": "01HCSAPQ9T81KRMTVAR8K2B97Y"
            },
            {
                "displayname": "Firstname   Lastname",
                "email": "[email protected]",
                "id": "01HE03CW81XC3D0WZR9SPNKX0E"
            }
        ]
    }
}

Get User Details

GET /account/user - Get logged in user’s details

Example Response:

{
    "user": {
        "createdby": "system",
        "createdon": "2020-07-14T21:30:24.286221+04:00",
        "deletedby": null,
        "deletedon": null,
        "displayname": "admin ",
        "email": "[email protected]",
        "firstname": "admin",
        "id": "01GGCG5ZPVXWA17JFGTS1HD03F",
        "lastname": " ",
        "meta": {},
        "middlename": " ",
        "mobile": null,
        "properties": {},
        "tags": null,
        "updatedby": "system",
        "updatedon": "2020-07-14T21:30:24.286221+04:00",
        "version": 1
    }
}

Update User Details

PUT /account/user - Update logged in user’s details

Example Request:

{
    "firstname": "admin",
    "middlename": "admin",
    "lastname": "admin",
    "displayname": "admin admin admin"
}

Example Response:

{
    "user": {
        "createdby": "system",
        "createdon": "2020-07-14T21:30:24.286221+04:00",
        "deletedby": null,
        "deletedon": null,
        "displayname": "admin  admin admin",
        "email": "[email protected]",
        "firstname": "admin",
        "id": "01GGCG5ZPVXWA17JFGTS1HD03F",
        "lastname": "admin",
        "meta": {},
        "middlename": "admin",
        "mobile": null,
        "properties": {},
        "tags": null,
        "updatedby": "[email protected]",
        "updatedon": "2023-10-30T15:14:17+04:00",
        "version": 2
    }
}

IAM API

Overview

Health & Status Endpoints

Health

Ready

Realm & Provider Endpoints

List Realms

List Auth Providers

Authentication Endpoints

Login With Email

Federation Login With Email

Login With Mobile

OTP (One-Time Password) Endpoints

Login With Email OTP

Approve OTP Token Login

Login Password With OTP MFA

Approve OTP Token Login (MFA)

TOTP (Time-based OTP) Endpoints

Login Password With TOTP MFA

Approve MFA TOTP Request

HOTP (HMAC-based OTP) Endpoints

Login Password With HOTP MFA

Approve MFA HOTP Request

WebAuthn Endpoints

Login Password With WebAuthn MFA

Webauthn Login Begin

Webauthn Login Finish

Webauthn Register Begin

Webauthn Register Finish

Magic Link Endpoints

Create Magic Link Login

Approve Magic Link Login

Check Approved Magic Token Login

Magic Numbers Endpoints

Create Magic Link Numbers Login

Approve Magic Link Numbers Login

Check Approved Magic Token With Numbers Login

Token Management Endpoints

Refresh JWT Token

Approve Kisai Auth Login

OAuth Callback Provider

MFA Validation Endpoints

Check MFA TOTP Request

Check MFA HOTP Request

Password Management Endpoints

User Password Reset Request

User Validate Token Password Request

User Password Reset Using Token Request

User Update Password

MFA Provider Management Endpoints

User Add TOTP MFA Provider

User Add HOTP MFA Provider

User Remove TOTP/HOTP/WebAuthn MFA Provider

API Key Management Endpoints

API Key With Expiry and Capabilities

API Keys by Service Name

API Keys by ID

Admin User Management Endpoints

Admin Create User

Admin Update User

Admin Get User by Email

Admin Get User by ID

Admin Delete User by ID

Admin List Users

Admin Lock User by Email

Admin Unlock User by Email

Admin Tenant Management Endpoints

Admin Create Tenant

Admin Update Tenant

Admin Get Tenant by Slug

Admin Get Tenants

Admin Delete Tenant by Slug

Admin Role Management Endpoints

Admin Create Role

Admin Update Role

Admin Get Role by Slug

Admin Get Roles

Admin Delete Role by Slug

Admin Tenant & Role User Management Endpoints

Admin Get Users for Tenant