R-NACOS Authentication Open API

Overview

This document describes the R-NACOS HTTP endpoints for login and authentication. R-NACOS supports the login protocols used by multiple Nacos SDKs and provides a unified authentication entry point.

Base URL: http://127.0.0.1:8848

Authentication Modes

R-NACOS supports two authentication modes:

• Authentication enabled: When RNACOS_OPENAPI_ENABLE_AUTH=true , obtain an accessToken through a login endpoint and include it in subsequent requests.
• Authentication disabled: When RNACOS_OPENAPI_ENABLE_AUTH=false , the login endpoint returns the fixed token AUTH_DISABLED ; requests do not require actual authentication.

Login Rate Limiting

Login endpoints are rate-limited. RNACOS_OPENAPI_LOGIN_ONE_MINUTE_LIMIT controls the number of login attempts allowed per username per minute. Exceeding the limit returns LOGIN_LIMITE_ERROR .

Token Lifetime

The RNACOS_OPENAPI_LOGIN_TIMEOUT setting controls token lifetime in seconds.

---

1. Standard Nacos V1 Login Endpoint

Endpoint: POST/GET /nacos/v1/auth/login

Description: Standard Nacos V1 login endpoint, compatible with the Nacos 1.x SDK.

Request Parameters

Parameter	Type	Required	Description
username	string	Yes	Username
password	string	Yes	Password

Parameters may be supplied through the query string or a form-urlencoded request body; both sources may be combined.

Response

Parameter	Type	Description
accessToken	string	Access token used to authenticate subsequent requests
tokenTtl	number	Token lifetime in seconds
globalAdmin	boolean	Whether the user is a global administrator

Example

curl -X POST "http://127.0.0.1:8848/nacos/v1/auth/login" -d "username=admin&password=admin"

Response:

{"accessToken":"a1b2c3d4e5f6...","tokenTtl":18000,"globalAdmin":false}

---

2. Nacos V1 User Login Endpoint

Endpoint: POST/GET /nacos/v1/auth/users/login

Description: Nacos V1 user login endpoint used by some Nacos 1.x SDKs.

Request Parameters

Parameter	Type	Required	Description
username	string	Yes	Username
password	string	Yes	Password

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

Parameter	Type	Description
accessToken	string	Access token
tokenTtl	number	Token lifetime in seconds
globalAdmin	boolean	Whether the user is a global administrator

Example

curl -X POST "http://127.0.0.1:8848/nacos/v1/auth/users/login" -d "username=admin&password=admin"

Response:

{"accessToken":"a1b2c3d4e5f6...","tokenTtl":18000,"globalAdmin":false}

---

3. Nacos V3 User Login Endpoint

Endpoint: POST/GET /nacos/v3/auth/user/login

Description: Nacos V3 user login endpoint, compatible with Nacos 2.x and 3.x SDKs.

Request Parameters

Parameter	Type	Required	Description
username	string	Yes	Username
password	string	Yes	Password

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

Parameter	Type	Description
accessToken	string	Access token
tokenTtl	number	Token lifetime in seconds
globalAdmin	boolean	Whether the user is a global administrator

Example

curl -X POST "http://127.0.0.1:8848/nacos/v3/auth/user/login" -d "username=admin&password=admin"

Response:

{"accessToken":"a1b2c3d4e5f6...","tokenTtl":18000,"globalAdmin":false}

---

4. R-NACOS User Login Endpoint

Endpoint: POST/GET /rnacos/v1/auth/user/login

Description: R-NACOS login endpoint with the same behavior and parameters as the other login endpoints.

Request Parameters

Parameter	Type	Required	Description
username	string	Yes	Username
password	string	Yes	Password

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

Parameter	Type	Description
accessToken	string	Access token
tokenTtl	number	Token lifetime in seconds
globalAdmin	boolean	Whether the user is a global administrator

Example

curl -X POST "http://127.0.0.1:8848/rnacos/v1/auth/user/login" -d "username=admin&password=admin"

Response:

{"accessToken":"a1b2c3d4e5f6...","tokenTtl":18000,"globalAdmin":false}

---

Error Codes

HTTP status	Description
200	Login succeeded
403	Login failed (incorrect username or password, rate limit exceeded, and similar errors)

Common Error Messages

• unknown user! - Incorrect username or password
• LOGIN_LIMITE_ERROR,Frequent login, please try again later - Login rate limit exceeded
• SYSTEM_ERROR - Internal system error

Response When Authentication Is Disabled

When RNACOS_OPENAPI_ENABLE_AUTH=false , the endpoint returns the following response even if the supplied credentials are incorrect:

{"accessToken":"AUTH_DISABLED","tokenTtl":18000,"globalAdmin":true}

---

Using the Token

After a successful login, use the returned accessToken in subsequent requests in either of these ways:

1. Query parameter: Append ?accessToken=xxx to the request URL.
2. Header: Add accessToken: xxx to the request headers.

---

Endpoint Compatibility Table

Endpoint	Use case	Compatibility
/nacos/v1/auth/login	Nacos 1.x SDK	Nacos 1.x
/nacos/v1/auth/users/login	Nacos 1.x SDK (some clients)	Nacos 1.x
/nacos/v3/auth/user/login	Nacos 2.x/3.x SDK	Nacos 2.x/3.x
/rnacos/v1/auth/user/login	Native R-NACOS endpoint	R-NACOS