Login Resource

The login resource is used to establish a session cookie associated with a user and to return a list of organizations a user belongs to. This is typically used by webpages as it requires passing a user's email address and password. A session cookie will timeout after a period of inactivity.

Use the api_key resource to make GroveStreams API calls without having to pass a user's email address and password.

POST login

---

Authenticates a user's email address and password. A session cookie is created after authentication succeeds. Returns a list of organizations the user belongs to.	Resource Information
	Rate Limited?	No
	session, oauth and org tokens compatible?	No
	api_key token compatible?	No

Parameters

none

Example Requests

/login

Request Body

{
  "email": "a_bogus_email@gmailx.com",
  "password": "DoDaDippity!"
}

Response Body
{
  "message": "Login succeeded.",
  "organization": [
    {
      "uid": "00000000-0000-0000-0000-000000000001",
      "name": "Home",
      "type": "organization"
    },
    {
      "uid": "00000000-0000-0000-0000-000000000002",
      "name": "Grove Streams Testing Suite",
      "type": "organization"
    }
  ],
  "userFirstName": "Fred",
  "userUid": "630114e8-76ac-46fc-866c-bb5e63258018",
  "userLastName": "Flinstone",
  "sessionUid": "45f4d3c6-0fc9-4c7b-b2d3-ae9350fe312f",
  "success": true
}

DELETE login

---

Expires the session (the one that is either a cookie or passed as an argument).	Resource Information
	Rate Limited?	No
	session token compatible?	Yes
	api_key token compatible?	No
	org token required?	No

Parameters

none

Example Requests

/login

Response Body
{
  "message": "Session ended",
  "success": true
}

POST login_guest

---

If an organization is marked as public then this API call can be made to create a session for a Guest user. The session will have access rights that the organization owner setup. This session never expires. There will be no list of organizations returned. The caller should be aware of the organization uid and set it as a cookie for future API requests or pass it as an argument.	Resource Information
	Rate Limited?	No
	session, oauth and org tokens compatible?	No
	api_key token compatible?	No

Parameters

none

Example Requests

/login_guest

Request Body
None

Response Body
{
  "message": "Logged in as Guest",
  "organization": [
   
  ],
  "userFirstName": "Guest",
  "userUid": "675a0bc6-cc9a-4b98-a2fc-fd596b045771",
  "sessionUid": "e4604653-6881-4df4-b003-0e44e6fa9ce6",
  "success": true
}

POST login2fa

---

Checks two-factor authentication (2FA) eligibility after username/password verification. Determines if 2FA is engaged for the user and returns available 2FA delivery options. Supports trusted device identification.	Resource Information
	Rate Limited?	No
	session, oauth and org tokens compatible?	No
	api_key token compatible?	No

Parameters

none

Example Requests

/login2fa

Request Body

{
  "email": "user@example.com",
  "password": "myPassword",
  "deviceId2Fa": "optional-trusted-device-id"
}

Response Body
{
  "message": "",
  "success": true
}

GET login2fa/code/{email}

---

Sends or resends a new 2FA verification code to the specified email address. Can optionally specify a preferred delivery method.	Resource Information
	Rate Limited?	No
	session, oauth and org tokens compatible?	No
	api_key token compatible?	No

Parameters

preferredOp

optional

The preferred delivery method for the 2FA code.

Example Requests

/login2fa/code/user@example.com
/login2fa/code/user@example.com?preferredOp=sms

DELETE login2fa/clear_trusted

---

Clears all trusted devices associated with the authenticated user's 2FA. Removes all device trust records, forcing re-verification on subsequent logins from previously trusted devices.	Resource Information
	Rate Limited?	No
	session token compatible?	Yes
	api_key token compatible?	No
	org token required?	No

Parameters

none

Example Requests

/login2fa/clear_trusted

Response Body
{
  "message": "Cleared trusted device list",
  "success": true
}

GET session_check

---

Checks if a valid, non-guest session exists for the caller. Returns the associated user's email address if authenticated, or "NULL" if no valid session exists. Useful for verifying session status.	Resource Information
	Rate Limited?	No
	session token compatible?	Yes
	api_key token compatible?	No
	org token required?	No

Parameters

none

Example Requests

/session_check

Response Body
Returns the user's email address as plain text if a valid session exists, or "NULL" if not.

GET session_end

---

Explicitly ends the current session. Terminates the user's authenticated session by invalidating the session. Can be used as an alternative to DELETE login for logout.	Resource Information
	Rate Limited?	No
	session token compatible?	Yes
	api_key token compatible?	No
	org token required?	No

Parameters

none

Example Requests

/session_end

Response Body
Returns "Session Ended" as plain text.