REST API Authentication

Authentication Methods

Two REST API authentication methods are available:

• API keys

• Session tokens

The REST API Documentation area at the top of the REST API documentation page provides summary information about both authentication methods.

For more information about API key authentication, read the following documentation.

About API Key Authentication

API key authentication requires each client to supply a key (token) to authenticate its requests to the Autoform DM REST API. This feature is an alternative to traditional 'username and password' authentication and is intended for use by any external system that integrates with Autoform DM.

Autoform DM application administrators can generate client-specific API keys for clients to use.

The REST API Documentation area at the top of the REST API documentation page provides an introduction to API key authentication.

What Is a Key?

A key is a unique string of numbers and letters, arranged into a prefix and a secret component, separated by a period:

[PREFIX].[SECRET]

The authenticated session that results from using a key to make a request lasts only for the lifetime of the request. So, when using API key authentication, there is no need to explicitly end sessions; they are automatically ended when Autoform DM completes the REST API request.

Security

API keys are secrets in the same way as passwords. So, after they are generated, they should be stored securely and not shared. Do not store a generated key in a source control system alongside programming code.

For projects using keys, it is recommended that you supply keys via system properties or other external means of configuration.

Warning

Autoform DM does not store API keys after it generates them. As a result, lost API keys cannot be recovered from Autoform DM.

Key Creation and Management

API keys can be created and managed either through the Autoform DM web application or through the api-keys resource of the REST API. Both methods provide operations for generating, listing, and revoking authentication keys.

The following information describes generating a key for a third-party system that will integrate with Autoform DM through the REST API.

API Key Creation and Usage Advice

We recommend that you first create a user account to represent the integration that will be using the API key to perform operations in Autoform DM. For example, you could create a user named transact-integration-user.

Note

Any attempt to use a key for a user who is not allowed to log in (for example, because their password has expired, or their account is disabled or locked) will fail.

So, you must ensure that the 'integration user' that you want to generate a key for has the appropriate Autoform DM role assigned to it and that the user account's password is set to never expire.

To generate a key, you must use an account that has permissions to generate keys. This account will 'own' the generated keys.

As this user, generate an API key. During the generation process, specify that the 'run-as identity' for the key is the name of the 'integration user'. Requests that use the generated key will be made under the identity of that 'run as identity' user account.

When the key has been generated, use it in the DM-API-KEY header of REST API requests. When the request is performed:

1. Autoform DM will use the supplied key to authenticate the request.

2. Autoform DM will create a session (that is intended to last for the lifetime of the request).

3. When the request is complete, Autoform DM will end the session.

The following sections describe how to manage (create and revoke) API keys.

Manage API Keys Through the Autoform DM Web App

API key management functions can be accessed via the Autoform DM web application.

Generate a Key

Navigate to the Administration area of Autoform DM as an admin user and then click the API Keys module.

Click Generate New Key. The key creation page opens.

Description: Enter a label to describe the new key.

Run As Identity: Enter the username of the account you want to use as the run-as identity. Requests that use the generated key will be made under the "run as identity" user's identity.

Note

Specifying a Run As Identity is optional. If you leave the box blank, the key's run-as identity will be the user creating the key.

Click Generate to continue.

If necessary, click Cancel to clear the fields and return to the previous page.

The generated API key will be displayed. You can select and copy it from the window. Store this key securely, because when the window is closed, the displayed value will be lost and cannot be recovered.

List Keys

Generated keys are listed on the API Keys page. Each key is identified by the prefix identifier (which is the part before the "." in the generated key).

Revoke a Key

To revoke a key, click Revoke in the relevant row of the API Keys page.

Then, to confirm the key revokation, click Revoke in the Revoke Key window. Autoform DM will remove the key and prevent any further usage of it.

Manage API Keys Through the REST API

The api-keys resource provides the operations for generating, listing and revoking authentication keys.

Generate a Key

Use the /api-keys (POST) endpoint to generate a key. In the API request's body, you can specify a label for the key.

A successful request will return the generated API key. This secret key is not stored in the system and must be stored securely; if it is lost, you must generate a new key.

Note

The format of an API key is [PREFIX].[SECRET]. Both elements are unique. The prefix can be used to identify a key and is specified when revoking a key.

Optional: You can specify runAsIdentity in this API request's body. Requests that use the generated key will be made under the "run as identity" user's identity. If you do not specify runAsIdentity, the owner and run-as identity will be automatically set to the user making the request. If you specify a run-as identity, ensure that a valid username within the system is chosen else the request will fail.

Click Execute. The response to the request will be shown.

List Keys

Use the /api-keys/{keyPrefix} (GET) endpoint to list a particular generated key. The details of the key (such as its owner, run-as identity, and label) are shown along with the prefix identifier.

Note

The secret component of the key is not included.

Revoke a Key

Use the /api-keys/{keyPrefix} (DELETE) endpoint to revoke a key. Specify the prefix of the key that you want to revoke, then click Execute.