Using API Key in SystemLink HTTP API

Updated Apr 8, 2025

Environment

Software

  • SystemLink
  • SystemLink Server

SystemLink HTTP API can be executed with API key instead of Basic Authentication. It is often used to prevent excess communication with authentication server. Here you will learn how to create an API Key and how to use it.

 

On the "Access Control" page of the SystemLink GUI, you will find Workspaces, Roles, and Users displayed as parallel options, though they have an underlying hierarchy. The API contains a greater number of objects with varied names. Here’s a brief summary for clarification:

 

GUI Elements:

  • A Workspace is a subset of items (Files, Tags, Systems, etc.) that can be managed, with a clear name (e.g., "Default").
  • A User is a login account (or a logical group of accounts) that is assigned one or more Roles in one or more Workspaces.
  • A Role is a collection of basic privileges with a clear name, such as "Systems Maintainer."
  • A Privilege is an atomic action that a user assigned to that "Role" can perform within any "Workspace" assigned to that user, such as "Upload files."

 

API Classes:

  • An API Key describes a collection of policies associated with a user, with an understandable name ("Super User Access")
  • A Policy describes a collection of statements that builds a complete set of permissions, with an understandable name ("Super User")
  • A Statement describes a collection of actions with an associated workspace, resource list, and understandable description ("File Maintainer")
  • An Action describes an atomic privilege like you see in the Role permissions list in the GUI (file:Query, file:Download, file:Upload, file:Update)

To create the API Key, we need to follow a bottom-up approach based on the containment relationship of the API Classes mentioned earlier.

 

Before starting the steps below, make sure you have access to the Auth Service Swagger UI page (go to <server_url>/niapis and choose Auth Service from the Select a definition dropdown menu) and have proper authorization to execute the HTTP Methods below. 

 

Note: By default, only the admin user can create API Keys.

 

  1. Create Policy (POST /niauth/v1/policies)
  2. Create API key (POST /niauth/v1/keys)
  3. Using The API Key

 

  1. Create Policy (POST /niauth/v1/policies)

    Policy is necessary to define action, resource and workspace for a user of specific name. In the following user1 is created with the policy ID of 0d92be8b-4772-4965-8f57-9e1644a03bf2.

    POST_policies2.png

     

    Notice that, for demonstration purposes, we are using the asterisk (*) wildcard, which means "all." Thus, our policy allows all actions on all resources of all workspaces. You can be more restrictive in your custom policy, but learning specific actions and resources is not trivial. A recommended way is to use the GET /niauth/v1/policy-templates, which includes examples of actions and resources you can use in your custom policy. Another option is to build your policy based on a policy template. You can do this by modifying the request body above, removing the "statements" property, and adding both "templateId" and "workspace" as top-level properties.

     

    You can create multiple API keys for a policy ID. When you will apply the same policy for multiple clients you can allow multiple clients to use a single API key. When you will allocate different actions, resources or workspace for each client, you have to create each policy for them.

     

  2. Create API key (POST /niauth/v1/keys)

    To create an API key, you need the the id of the policy you obtained in the previous section. Here, the API key is given as secret = aOFkYvM8eaypigGpMUmxbHRn-NhjkPTOTmahQbWHYS for name = user1 and policy ID0d92be8b-4772-4965-8f57-9e1644a03bf2.

    POST_keys2.png

     

    Once you've completed the previous steps, your API Key will be generated. Provide the secret for your user and keep a record of the id. If you need to update or remove the API Key later, you'll require the API Key ID.

     

    The next section shows an example of how to use the secret of an API Key in a LabVIEW code.

     

  3. Using The API Key

    By adding API key as a x-ni-api-key header you can send your HTTP request without basic authentication. Here, there is an example to get all API key name and ID. (You cannot see the value of secret. API key itself is hidden.)

    checkapikeyresults.png

    CheckAPIkey.png

    To the top

Was this information helpful?

Yes

No