Does the groov View API work with groov EPIC?

Yes, the View REST API is used to access groov data-store tags used in your groov View via the Devices and Tags interface in groov View Build. See the EPIC page of this guide for specific instructions.

How do you find a tag id?

Connect to groov in your web browser and open groov Build. Choose Configure > Devices & Tags. Highlight the Data Store and click Configure Tags. The tag id is listed for each tag.

Data Store tag id

How do you find your API key?

API keys are visible to Admin users in groov Build. To find them, open groov Build and choose Configure > Accounts. Each user’s API key is shown here.

User and API key list

Note that while all users have API keys, currently only Editor and Admin users can use the API.

To find your API key for groov EPIC go to the groov Manage accounts menu and select the user. More details can be found on the EPIC page.

How do you supply API keys in your requests?

There’s a more detailed explanation of how API keys are supplied in the Getting Started, but in short, groov accepts API keys in two ways:

  1. Via an HTTP Basic Authorization header. The API key is supplied as the User portion of the Authorization header, without an accompanying password.
  2. As a query parameter named api_key appended to any request.

Using the HTTP Basic Authorization header is preferred, mostly because it will prevent your API key from being visible in request logs. That said, HTTP Basic Authorization requires that the client base64 encode the API key, so groov accepts keys via a query parameter for convenience.

Should you create an API-only user?

While there’s no need to, creating API-only users for your individual applications is a good general practice. Here’s how:

  1. Create a new Editor user with a name that identifies the application you intend to use it with.
  2. Give it a strong, random password.
  3. Throw that password away.
  4. Use that user’s API key in your application.

To create an API-only user on groov EPIC:

  1. Go to groov Manage.
  2. Navigate to the Accounts menu.
  3. Choose Add to create a new user.
  4. Set the Username and a strong, random password.
  5. Make sure the user has groov View Editor permissions.
  6. Select Save.
  7. Choose that user from the account list and copy the API key to use in your applications.

How do you revoke/reset a user’s API key?

In the Manage Accounts panel (in groov Build, choose Configure > Accounts), click the Edit (pencil) icon next to the user.

Locating the Edit User button

In the Edit User dialog box that appears, click the Generate button next to the user’s API key to generate a new key, and then click “Update User” at the bottom to save your change.

To revoke/reset a groov EPIC user’s API key go to that user in groov Manage’s accounts menu, then select *Generate new key** and hit OK.

Why does the Swagger-UI page allow me to make some requests without authenticating?

You can reach the Swagger-UI page on your groov in groov Build; choose Help > groov Public API. Because this page is hosted on the same domain as groov itself, it inherits groov’s HTTP cookies.

When a cookie for a valid groov login session is set, the API endpoints allow access to queries that won’t change any of the groov project’s state without any additional authentication. So if you’re reading tags, no authentication is required. But if you try to write to a tag, you have to provide the API key.