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

Admin actions can be called through the JSON admin routes with Basic Auth, using the ADMIN_API_TOKEN described below. If you can perform an action in the /admin interface in a web browser, you can usually make the same request by appending “.json” to the admin URL and sending the Authorization header instead of signing in. The admin web pages themselves (and the Sidekiq, GoodJob, PgHero and Flipper dashboards) only accept a signed-in admin user, never an API token.

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 to the JSON admin endpoints and to any of the 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.

Application API tokens

API tokens created on the /api_tokens page can't be used for the admin API, even when they belong to an admin user. Use ADMIN_API_TOKEN instead. (Versions up to c224e10e07 also accepted an admin user's API token on admin routes.)

Synchronous vs. Asynchronous requests

When you append .json to the end of an admin URL, any import or export requests (aka “Account Migration” jobs) will be performed synchronously by default. This means that request will wait for the export or import  job to finish before returning a response. You should then check the response to ensure that the “state” is “processed”.

If you want to perform an asynchronous request that returns immediately while running the job in the background, you can add the “async=true” query parameter. This is recommended if you are exporting or importing a large number of templates, because a synchronous request gives up with an error after 3 minutes. (The job keeps running in the background, and you can find it on the /admin/account_migrations page.)