RUAL Docs - Cluster - API - Authentication

auth/login POST

Utilize this API to initiate an authentication process for any user account within the cluster.

Key	Type	Example
username	`string`	`"joe"`
password	`string`	`"*********"`

{ "access_token": "1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a", "expiry": 1708195948, "expiry_renew": 1209678, "verified": false, "2fa": [ "mobile", "totp", "otp" ], "default_2fa": "mobile", "user": { "username": "joe", "language": "en", "firstname": "Joe", "lastname": "Do", "code": "XXX", "_meta": { "guid": "39336c0c7cec1c89f617ed704b34c2ad39336c0c7cec1c89f617ed704b34c2ad" } }, "ip": "127.0.0.1" }

{ "success": false, "error": "ERROR_KEY" }

Error Code	Description
INVALID_TOKEN_DATA	the credentials provided are incorrect or have expired.
INVALID_AUTHENTICATION_GROUP	the user belongs to an invalid authentication group.
INVALID_IP	the IP address is not authorized to access the cluster. This restriction only applies to users in specific authentication groups.

auth/mobile/request POST

If a token is unverified, you can request a 2FA SMS code using this API. This request is automatically triggered when the user's default 2FA method is configured as mobile.

Key	Type	Example
access_token	`string`	`"1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"`

{ "resend": true }

{ "resend": false }

auth/mobile/verify POST

If a token is unverified, you can validate it by utilizing this API with the user-provided 2FA token.

Key	Type	Example
access_token	`string`	`"1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"`
token	`string`	`"48 01 94"`

{ "verified": true }

{ "verified": false }

auth/otp/verify POST

If a token is unverified, you can validate it by utilizing this API with the user-provided 2FA token.

Key	Type	Example
access_token	`string`	`"1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"`
token	`string`	`"25890226bfe4de7952bcc8f4268efb14"`

{ "verified": true }

{ "verified": false }

auth/totp/verify POST

If a token is unverified, you can validate it by utilizing this API with the user-provided 2FA token.

Key	Type	Example
access_token	`string`	`"1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"`
token	`string`	`"692849"`

{ "verified": true }

{ "verified": false }

auth/logout POST

With this API you can invalidate the current token and logout the user.

Key	Type	Example
authorization	`string`	`"Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"`

{ "logout": true }

{ "success": false, "error": "ERROR_KEY" }

auth/token GET

Retrieve the details of the active access token, including its expiration time, associated user data, and authorized scopes. This endpoint allows you to verify token validity and fetch session information for the authenticated user.

Key	Type	Example
authorization	`string`	`"Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"`

{ "expire": 1234567890, "user": { "username": "joe", "firstname": "Joe", "lastname": "Do", "_meta": { "guid": "39336c0c7cec1c89f617ed704b34c2ad39336c0c7cec1c89f617ed704b34c2ad" } }, "scopes": [ "admin", "user" ] }

{ "success": false, "error": "ERROR_KEY" }

Error Code	Description
ERROR_KEY	an error occurred while retrieving the token details.
INSUFFICIENT_PERMISSIONS	you do not have sufficient permissions to access this resource.

auth/token/active GET

Retrieve a list of all currently active access tokens along with detailed session information. This includes metadata such as one-time usage, verification status, activity timestamps, and renewal intervals, as well as user details, authorized scopes, client agent data, and the originating IP address. Use this endpoint to monitor and manage active sessions.

Key	Type	Example
authorization	`string`	`"Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"`

{ "onetime": false, "hide_session": false, "verified": true, "last_verified": 1736704149, "expiry_renew": 1209600, "last_activity": 1739708171, "expire": 1234567890, "user": { "username": "joe", "firstname": "Joe", "lastname": "Do", "_meta": { "guid": "39336c0c7cec1c89f617ed704b34c2ad39336c0c7cec1c89f617ed704b34c2ad" } }, "scopes": [ "admin", "user" ], "agent": { "name": "Mozilla", "version": "5.0", "os": "Windows", "platform": "Win32", "device": "Desktop" }, "ip": "235.19.104.246", "_meta": { "guid": "3f51a763573adbac26a0b3b602f796a1d046e3b13562dc7b6fc221f46f51cea2a01" } }

{ "success": false, "error": "ERROR_KEY" }

Error Code	Description
ERROR_KEY	an error occurred while retrieving active access tokens.
INSUFFICIENT_PERMISSIONS	you do not have sufficient permissions to access this resource.

auth/token/:guid DELETE

Revoke the specified access token using its unique GUID, effectively deactivating it and ending the associated session. Use this endpoint to invalidate tokens that should no longer grant access.

Key	Type	Example
guid	`string`	`"39336c0c7cec1c89f617ed704b34c2ad39336c0c7cec1c89f617ed704b34c2ad"`

Key	Type	Example
authorization	`string`	`"Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"`

{ "guid": "39336c0c7cec1c89f617ed704b34c2ad39336c0c7cec1c89f617ed704b34c2ad" }

{ "success": false, "error": "ERROR_KEY" }

Error Code	Description
ERROR_KEY	an error occurred while revoking the access token.
INSUFFICIENT_PERMISSIONS	you do not have sufficient permissions to access this resource.

Cluster

Blocks

Deployment

Interfaces

Blueprints

Other

Authentication APIs