Skip to content

Authenticate to the Profinity REST API

Profinity APIs require a Bearer token, which is either a service account token or a token returned by signing in with a username and password. Either way, use an account that is dedicated to the client and holds only the permissions the client needs. For a guided first call, refer to Make your first API call.

Use a service account token

A service account token is generated on the account's User Actions tab in Users & Groups, and it is already a Bearer token. A client that has one skips the /api/v2/Users/Authenticate call and passes the token directly in each request. In Swagger, paste the token into the Authorize dialog. The token lasts indefinitely and has no refresh token, so it suits a client that runs for a long time or unattended.

It stays valid until an administrator generates a new one, changes the account's roles, or disables the account.

Sign in with a username and password

Signing in needs no licensed feature, but a user account comes with the Profinity Server licensed feature, as described in Licensing.

To test the APIs from the Swagger page without a service account token, execute a call against /api/v2/Users/Authenticate on that page. Then apply the returned token with the Authorize button of the Swagger page.

To get a token from any other client:

  1. Send a POST request to http://localhost:18080/api/v2/Users/Authenticate. Put the username and password of the Profinity user that the API calls run as in the JSON body, for example:

    {
  "username": "<username>",
  "password": "<password>"
}

    Replace <username> and <password> with the credentials of that user.

  2. Read the response. If the username and password are valid, Profinity responds to a non-browser client with a JSON body. The body carries the access token, a refreshToken (omitted for service accounts, whose tokens do not expire), the username, an id and the user's permissions. This example abbreviates the permissions list:

    {
    "token": "eyJhbGciOi...",
    "refreshToken": "...",
    "username": "<username>",
    "id": "<username>",
    "permissions": ["TagView", "..."]
}

Use HTTPS to protect passwords

Calling this API over an HTTP connection can expose the password to network scanning. Custom applications running on the Profinity server can use the localhost address, which does not carry this risk. An application that calls Profinity across a network uses HTTPS for all API usage.

The Swagger POST /api/v2/Users/Authenticate call with a username and password in the request body and a 200 response that returns a token

Generating a Bearer token on the Swagger page

A browser client receives the same session as cookies and a body that omits the token. A user who must complete two-factor authentication or change a password first receives a preAuthToken instead of a token, with requiresTwoFactor or requiresPasswordChange set. Complete the sign-in through /api/v2/Users/Authenticate/TwoFactor or /api/v2/Users/Current/ChangePassword. A token that is still valid can be renewed with GET /api/v2/Users/Refresh.

Pass the token in requests

Pass the service account token, or the contents of the token field, in each request as a Bearer token. The documentation of the client-side tool calling Profinity describes how to do this for that tool. From a command line, this request returns the latest sample of a tag:

curl -H "Authorization: Bearer <token>" http://localhost:18080/api/v2/Tags/Sample/<full-tag-path>

In Windows PowerShell, type curl.exe instead of curl, because curl is an alias for another command there.

Replace <token> with the token and <full-tag-path> with the full path of the tag.

In Swagger, select the Authorize button and paste in the generated token:

The Swagger Available authorizations dialog with an empty Value field, an Authorize button and a Close button

Entering the token in Swagger

A request that returns data shows the token works.

Fix 401 and 403 responses

What you see Cause What to do
A 401 response. The token is missing or has expired. A client that signed in with a username and password signs in again to get a new token. A client can also renew a token that is still valid with GET /api/v2/Users/Refresh before it expires.
A 401 response from a client that uses a service account token. The old token stops working when a new one is generated or the account's roles change. Get the current token from an administrator.
A 403 response. The user lacks the permission the route needs. Use an account that holds the permission the route needs.

To read tag data with the token, refer to Read real-time and historical tag data.