API keys

Plexus Connect allows user login by API key to be able to use Connect APIs. It is the additional means of login specifically designed for using Connect features outside of the Connect UI.

There are two parts. The management of API keys and using the defined API keys.

Management

Consists of UI and APIs for creating, editing and deleting the API keys.
For Management to be active the business flag API_KEYS_LOGIN must be enabled. When the Management is active, there is new option in the main menu.

Menu option leads to the Management dialog.

There any user can create API keys for himself linked to specified schemas selected by user. New API keys will be by default valid for 180 days. After that, they will expire.

The validity of API keys can be changed by setting the value plexus.apiKeys.validityInDays in nps.properties file.

It is not possible to extend the validity duration, so after expiration, new keys must be created. Each user can modify or delete the API keys as they see fit. Modification allows only changing the "comment" of the API key. Each user can also delete the API key, however it effectively means, the key will be considered expired by that action, but the key will still remain in the database for audit purposes.
Administrator users are allowed to modify and delete all API keys, even those belonging to other users, however, they cannot create new API keys for other users.

API keys are stored in the IJC_API_KEYS database table. They will stay there, unless manually deleted by DB administrators.

Login by API key

Login by API key is always enabled, however without management of the API keys it is not possible to create valid API keys. User, who wants to use his API key, has to copy the key value from the API key Management dialog in the Connect UI.

Typical use case than would be using the copied API key value in Python Scripting, where user just inserts his API key into his script instead of a previously used username/password. Also, the server schema ID or ids must be added to the script, because API keys are linked to set of schemas previously selected by user.

You can get the server schema ID from the URL, it is the first part of the view address, see picture below: Picture shows, the server schema id is 6C6F63616C6462.

See example script below:

    from connect_api import DataApi
    # DataApi("apiKey", ["serverSchemaId"]) or DataApi("apiKey", ["serverSchemaId1", "serverSchemaId2"]) for 2 schemas
    api = DataApi("6i9MYZxHxJMvHn4qyJ2vAockLzqllbNk", ["6C6F63616C6462"])
    session = api.copySessionFromURL("http://localhost:3002/form/6C6F63616C6462_ECFAB82DF4F379B98013761D17151C34/4?search1%2FDEE7DBBC35E95BB9494A1CB9F1536160%2F2=0-%3E,1-300&sorts=ascending-true,fieldId-DEE7DBBC35E95BB9494A1CB9F1536160,widgetId-194A0883A70F1BFE4B5F9487A9089252&childSel=C15079B06FDA5FD35173EBD5E3BC9DB5-2")
    result = session.getData(["ID", "EST.LOGKOW"])
    print(result)
    session.close()

When using Schema refresh by IJC, IJC automatically creates its own API key (bound to the user who initiated the Schema refresh), uses it and then discards it afterwards.

It is possible to use API keys on your own and call the APIs manually or by your script or program. See example below when using curl to access the API of Connect:

• The first request will return XSRF-TOKEN and PlexusSessionId in Cookie.

  • curl -i localhost:8080/xsrf
  • results in getting set-cookie headers with PlexusSessionId and XSRF_TOKEN
  • make sure, you don't follow the redirect if it happens, so you have access to cookies above

• Use POST to log in and use token from the UI, don't forget to add headers and cookies from previous request.

  • curl -i -X POST -H "X-XSRF-TOKEN: XSRF_TOKEN" -H "Cookie: XSRF-TOKEN=XSRF_TOKEN; PlexusSessionId=PlexusSessionId" -H "X-Schema-Ids: schemaId1:schemaId2:etc" -H "Authorization: ApiKey <YOUR_APIKEY>" localhost:8080/api-key-login
  • this will log the user in and return new PlexusSessionId in the cookie (reference it as PlexusSessionId2 for now), if login is successful, otherwise it will return http status 401

• Call again the request for XSRF_TOKEN, but add there a header with new PlexusSessionId2.

  • curl -i -X GET -H "Cookie: PlexusSessionId=PlexusSessionId2" localhost:8080/xsrf
  • the result will be new xsrf token in set-cookie header - reference it as XSRF_TOKEN2 for now

• You are now logged in and have PlexusSessionId2 and XSRF_TOKEN2, which now should be part of each request to Connect APIs.

• Verify you are logged in, dont forget to add specified headers and cookies.

  • curl -i -X GET -H "X-XSRF-TOKEN: XSRF_TOKEN2" -H "Cookie: XSRF-TOKEN=XSRF_TOKEN2; PlexusSessionId=PlexusSessionId2" localhost:8080/rest/user/signedInUser
  • This should return 200 and body with “userName”

Notes:
Usage of API keys is logged in the log. All unsuccessful login attempts are logged as well. Each key has also date and time of its last usage stored in the database, it can be used for audit purposes.