Configuring API Key Authentication¶

Vinyl REST APIs can be secured using API keys. Setting up API key authentication involves the following procedures:

1. Creating a Vinyl Security Provider.
2. Generating an API key.

Requirements¶

In order to proceed, you will need:

• Administrator access to Vinyl.
• REST API for testing.

Creating a Vinyl Security Provider¶

1. API key authentication is enabled within Vinyl via a security provider. Start by signing into Vinyl as an administrator.
2. Navigate to the IDE
3. Click the Security Providers button
4. In the User Authentication panel, click the + User Authentication button

5. Provide the following:

   • Name: API Key
   • Type: API Key
   • Active: Checked
   • Priority: A integer between 10 and 100 (e.g. 50). Note that this value must be unique.

6. Click the Save button

Generating an API Key¶

API keys are associated with Vinyl users. To generate a new API key, start by signing into Vinyl as an administrator.

1. Navigate to the IDE
2. Click the User Management button
3. In the Users panel, locate the user for which you would like generate an API key
4. Click the Open Record icon (Popup)
5. Click the Keys icon (Key)
6. Click the Create button

7. Provide the following:

   • Provider: API Key
   • Description: Description of key purpose. For example: Provides access to the REST API

   • Expires In: Lifetime of the API key in minutes. Once generated, the lifetime cannot be changed.

     

8. Click the Save button

Note the generated API key. It will take the form of a base64url-encoded, 128 bit integer. Example: DLOo9sPS5slJEMHpXBFt3g

Testing the API Key¶

The following demonstrates how to authenticate a REST API request using an API key.

GET /rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g