General - Authenticate.adoc

General - Authenticate

A HTTP POST to /api/edge/auth.json will create a session on the device, however this method is designed to be used internally (and is used internally by the login form), so it does not expose any session ID headers useful for validating login status but does pass it to the internal code.

Table of Contents

• Request
• Response
  • Root
  • platform Object
  • poe_cap Object
• Examples
  • Valid Login

Request

A HTTP POST to https://host-or-ip/ with the username and password encoded as a simple application/x-www-form-urlencoded form.

Name	Type	Values	Description
username	String	String	The username of a user.
password	String	String	The password of a user.

Response

Root

Name	Type	Values	Description
success	String	A boolean encapsulated in a string (e.g. "0" or "1")	Whether the API request was successful.
error (Optional)	String	An error message (e.g. "The username or password you entered is incorrect")	The error that occurred while trying to process this authentication request.
level	String	"admin" or "operator"	A value that represents the role / privilege level of the authenticated user.
started	String	A number encapsulated in a string (e.g. "1513")	Device uptime in seconds.
default-config	String	A boolean encapsulated in a string (e.g. "false" or "true")	Whether the device is running the factory default configuration.
platform	Object	platform object	Contains information about the current device capabilities.

platform Object

Name	Type	Values	Description
model	String	A model name (e.g. "ER-4")	A string that represents a device model from devices.json.
poe_cap	Dictionary	poe_cap object(s)	A dictionary that represents the device Power over Ethernet (PoE) capabilities.

poe_cap Object

Name	Type	Values	Description
Key	String	An interface name (e.g. "eth0")	The unique name of a physical interface.
Value	String	A signed numeric value encapsulated in a string (e.g. "1", "0" or "-1")	The Power over Ethernet (PoE) capabilities of a specific physical interface.

Examples

Valid Login

POST /api/edge/auth.json Request

username=USERNAME&password=PASSWORD

POST /api/edge/auth.json Response

{"success": "1", "level": "admin", "started": "1513", "default-config": "false", "platform": {"model": "ER-4", "poe_cap": {"eth0": "0", "eth1": "0", "eth2": "0", "eth3": "0", "eth4": "-1"}}}