API Keys

What is an API Key

An API Key is a unique identifier used to authenticate and authorize a user, application, or system to access specific data or services within an API (Application Programming Interface). It acts as a security token that enables secure communication between different software components, ensuring that only authorized entities can interact with the data or functionality offered by the API. They are typically passed along with API requests in headers or as query parameters, and they can be configured with specific permissions, such as read-only or full access, to control the level of access granted.

An API Key allows you to grant access to a Data Collection only to specific users or systems. In the Data Hub API Keys offer several powerful features to ensure secure and flexible data access. You can easily enable or disable API Keys, granting or revoking access as needed for specific users or systems. To enhance security, you can set IP filtering, restricting access of the API Key to specific IP addresses. Additionally, you can configure an expiration date to ensure that access is temporary and automatically revoked after a defined period, reducing the risk of unauthorized access over time. The ability to define predefined headers also adds another layer of control, allowing you to customize authentication details, metadata, or additional security measures within the request headers.

Navigation to the API Keys page

To get to the API Key page from the dashboard, find the Data Hub Tile and select Data Collections.
If the tile shown is deactivated, you do not yet have a Data Hub license. In this case, please contact sawsconnector@saws.de.

If you are not on the dashboard click the most left button in the toolbar to navigate to the dashboard page.

If you are already in the Data Hub you can use the dropdown menu in the toolbar and select the API Keys item.

Now you should be in the API Keys page which shows the API Keys table list.

Creating an API Key

To create a new API Key, click on the Plus Button on the top left corner of the API Keys table.

The Editor will open where you can configure the metadata of your API Key which consists of the following:

• Access Type
• Name
• Status
• IP Filter
• Expire Date
• Header

Access Type

The Access Type allows you to choose the method through which you will access the API, providing flexibility based on your needs and security requirements.

API Key

The API Key option generates an API key specifically for your use, granting access to the API with a predefined set of permissions. This option is ideal for straightforward integrations where a unique key is needed for access.

api.contentserv.com Token

The api.contentserv.com Token option enables you to select specific users or projects that are allowed to use the token, providing a more controlled and secure approach by limiting access to authorized entities. This is particularly useful when working in teams or across multiple projects where access needs to be restricted to certain users or environments.

Generic Token

The Generic Token option allows you to define your own API key, giving you complete control over the token’s generation and usage. This option is suitable for advanced use cases where custom configurations are required, offering flexibility in how the key is managed. Each of these options ensures that you can choose the most appropriate level of access control for your integration, ensuring both security and ease of use.

Name

The name should be descriptive and unique.

Status

The status defines if the API Key is active or not. Requests with an inactive API Key will always result in an error.

IP Filter

The defined API token is only valid if the request comes from one of the defined IP Filter. Each IP Filter consists of an IP Range and a Netmask.
The IP Range has the format ‘x.x.x.x’ where every ‘x’ must be a number between 0 and 255 without leading zeros (e.g. 192.168.178.1). You can use the same format for the Netmask or a number between 1 and 99.
This is especially useful when you work with local networks.

We strongly recommend limiting the access of the individual Data Collections / API Keys to IP addresses. Especially when it comes to server to server communications. This is an important security mechanism in addition to the key itself.

Expire Date

With the Expire Date you can validate an API Key until a specific Date. If a request is done with an API Key which is expired the request will result in an error.
If you do not set an Expire Date the API Key will never expire.

Header

Here you can define Header which will be set in the response header of a request with this API Key. You can either define fix values or use the predefined values “${collection.meta.count}”, “${collection.meta.name}”, “${collection.meta.limit}” or “${collection.meta.offset}” which will be dynamically filled depending on the request and Data Collection.  Header which are marked with a check will not be included. In the example below the header x-id will not be set in the header.

Save

Now you should be able to save your API Key. It should look like this:

Further Informative Fields

After the save was successful the API Key contains a few more automated fields:

• API Key
• Created
• Last Record Change
• Sync Status

API Key

If you Access Type is API Key, the field API Key appears where you can show/hide, copy or regenerate your generated API Key.

Created

The Created field shows you the date when the API Key was created. If you have just created an API Key it should show you the current date.

Last Record Change

The Last Record Change field shows you the date of your last record change. If you have just created an API Key this field should be empty or show the creation date.

Sync Status

The synchronization of your API Key can take a little bit of time depending how busy the servers are.
For more information read the Sync Status article.

Endpoint Tab

After you created your API Key there will be an additional Endpoint tab which will help you identifying dependencies and references in Endpoints.

Was this article helpful?

0 0

How can we improve this article?

Please submit the reason for your vote so that we can improve the article.

Name

Email

Submit