OAuth 2.0


GroveStreams is an OAuth 2.0 authorization service. OAuth 2.0 is a standard that allows other services, such as Amazon Alexa, the ability to use the GroveStreams API without storing user names and passwords on a device.

An external service makes several calls to our OAuth 2.0 HTTP APIs to:
  • Obtain a Grant Code token after being authenticated by our authentication page.
  • Use the Grant Code token to obtain an Authorization token and a Refresh token .
  • The caller can now save and use the Authorization token to make GroveStreams API Calls.
The authorization token will have the same rights that are configured for the authenticated GroveStreams user.


Authorization URL
POST https://grovestreams.com/Modern/#signinoauth/

Parameters:
  • response_type: must be "code"
  • client_id:
  • state: Optional
  • redirect_uri:
  • email: Optional. Will populate the user email field with this value on the authentication page if one is passed in.
This authorization URL will display a GroveStreams authorization page prompting the user for their user name and password. The redirect_uri will be called with the state and an authorization code parameters after the user authenticates successfully. The authorization code will expire in one hour.

The name of the your Brand and your logo will appear within the authentication page if you use your branded domain as part of the authorization URL above.


Access Token URI
POST https://grovestreams.com/api/oauth_access_token

Parameters:
  • grant_type: Must be either "authorization_code" or "refresh_token"
  • code: The grant code returned by the authorization URL. Not required if passing a refresh_token.
  • client_id: Must match what was passed in with the authorization URL.
  • state: Optional
  • client_secret: Optional. It is required if one was passed in for the authorization_code and a refresh_token request is being made.
  • redirect_uri: Optional. Must match the redirect_uri passed in with the authorization URL if it is included in this call.
  • refresh_token: Optional. Pass a refresh token along with grant_type=refresh_token to get a new grant token.
Response: 
						HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "access_token":"70d9e020-5ada-37c2-a653-e9052bda32d3",
   "token_type":"bearer",
   "expires_in":86400,
   "refresh_token":"807c1516-f632-387a-90a4-57921b6d1581"
}

The access token URI requires a grant code. It will return an authorization token and a refresh token. The authorization token will expire after 24 hours. Use the refresh token to obtain a new authorization token.

Using the Authorization Token
Use the authorization token anywhere you would typically use a session token. Include the token in the header of each call like this:
Authorization: Bearer 70d9e020-5ada-37c2-a653-e9052bda32d3

Include an org cookie or URL parameter if the API call is specific for an organization.

How to Obtain a Grant Code Without a Browser

Some environments might not support the ability to use our Authorization web page. You can make the call below to obtain a grant code given a user email and password:

POST https://grovestreams.com/api/oauth_login
Request JSON Body: 
{
  "email": "bbb@grovestreams.com",
  "password": "bbb",
  "scope": "xx",
  "response_type": "code",
  "state": "zzz",
  "redirect_uri": "http://acme.com",
  "client_id": "123"
}
Response: 
{
  "success": true,
  "oauthCode": "490691af-dd3a-3982-8b2b-629cba9f2065",
  "oauthState": "zzz",
  "message": "Login succeeded.",
  "oauthRedirectUri": "http://acme.com"
}