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.

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.

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.

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.