DocSpring Enterprise provides an internal admin API that you can use to automate and administer the application. These actions include importing and exporting templates, creating a new account, and adding new users.

Authentication

Any admin action can be called with Basic Auth API authentication. (e.g. If you can perform any action in the /admin interface by using a web browser, then you can make the same request by authenticating with the Authorization basic auth header instead of signing in with a username and password.) You should be able to append “.json” to most admin URLs to receive JSON formatted responses.

ADMIN_API_TOKEN Environment Variable

You can set the ADMIN_API_TOKEN environment variable to enable API authentication using a predefined API token. The token you set in this variable can contain any characters, and it can be any length.

You can then authenticate using a base64-encoded Basic Auth Authorization header, where the username is the literal string: ADMIN_API_TOKEN, and the password is the string that you set in the ADMIN_API_TOKEN environment variable.

For example, if you set ADMIN_API_TOKEN=apitoken1234, then you would encode the following string to Base 64: ADMIN_API_TOKEN:apitoken1234 => QURNSU5fQVBJX1RPS0VOOmFwaXRva2VuMTIzNA==

You would then send the following Authorization header to authenticate any API requests:

Authorization: Basic QURNSU5fQVBJX1RPS0VOOmFwaXRva2VuMTIzNA==

You will now be able to send requests for any of the admin or application API endpoints.

Which user is used when authenticating via ADMIN_API_TOKEN?

• If you have already run rake db:seed to set up an initial admin user, then your API request will be authenticated using this initial admin user.
• If your database is empty or contains no admin user, then your API request will be authenticated as an ephemeral admin user that does not exist in the database. This is mainly used to import an Account Export Archive into a fresh database, where the import will create all of the account, user, and template records that were exported.
  • It is not possible to import a single Template Export Archive in this way, because this action requires an existing account.
  • Most other API endpoints will fail when authenticating with this ephemeral admin user, since it does not belong to an account.

API Token Database Record

You may also make admin API requests by authenticating with an application-level API token. The user who created this API token must be an admin user.

When you are signed in as an admin user, you can create a new API Token record in the DocSpring application interface (on the /api_tokens page.)

This authentication method uses the same Basic Auth Authorization header as the application API endpoints, where you use the API token ID as the username, and the API Token Secret as the passport.

Synchronous vs. Asynchronous requests