API Key-Based Authorization

Using an API key allows a user to receive a permanent authorization grant. Unlike access and refresh tokens that expire after a specific period of time, an API key is active until the associated user identity is disabled or deleted.

To configure API key-based authentication:

Log in using one of the methods described in the Username and Password and OAuth 2.0 Authentication sections.
Send the HTTP POST request to the /users/{userUid}/logins/apikey path, where userUid is the UID of your current user account. Additionally you must provide the following query string parameters:

description — contains information about the API key issuance.
scopes — defines array of services to which the API key grants access. You can specify the following values:

ui — allows a user to send UI requests.
rest — allows a user to send REST API requests.
integration — allows a user to configure integrations.

If you want a user to have access only to GET operations, provide the true value for a isReadAccessOnly query parameter

The response body will contain a resource representation of a new user identity with the API key in the parameters property.

Request:

POST https://vspc:1280/api/v3/users/955b0b80-03b2-49fd-bf38-14785ecff0a8/logins/apikey?description=Portal Operator API Key&scopes=["integration","rest"]&isReadAccessOnly=true

Request Headers:

Content-type: application/json

Authorization: Bearer <Access-Token>

Response Code:

200 OK

Response Body:

{

"data": {

"id": 12,

"userUid": "955b0b80-03b2-49fd-bf38-14785ecff0a8",

"userName": "alpha_admin",

"companyId": "3b139961-6b11-4fd8-9e87-c2be1b0e9ca8",

"companyName": "Alpha",

"identityProviderName": "AK",

"description": "Portal Operator API Key",

"isReadAccessOnly": true,

"scopes": [

"integration",

"rest"

"status": "enabled",

"parameters": "4baccb809a3578f4xZGp74ik1k54wD03Y25fJ7KRIR7oVJsfgyFuQj4yaCFkhQMA5qjHyETS95PCy3uKcNm2bz6NrtVFHELWPh7mZxpx6cczHZYAbuufuy2QQ7zeKvkM",

"identifierInProvider": 11217524525076510964,

"creationDate": "2020-08-18T16:02:26.0136931+00:00"

}

API key can be used instead of the access token in the Authorization headers of all further requests.

Authorization: Bearer 4baccb809a3578f4xZGp74ik1k54wD03Y25fJ7KRIR7oVJsfgyFuQj4yaCFkhQMA5qjHyETS95PCy3uKcNm2bz6NrtVFHELWPh7mZxpx6cczHZYAbuufuy2QQ7zeKvkM

You can temporarily restrict access with the issued API key. To do that, set the disabled value for the status property of the user identity resource associated with that API key. For details on how to modify user identities, see Modify User Identity.

If you want to disable access to REST API with the issued API key permanently, you can delete the user identity resource associated with that API key. For details, see Delete User Identity.