REST API Authentication (Developers)

Every call to the REST API is authenticated by an Authorization header — there are no cookies and no server-side login state you must maintain. The API accepts three credentials: an API token (recommended), a username and password, and a short-lived session GUID you can obtain after signing in. All endpoints live under your site's base URL, for example https://yoursite.docmgt.com/rest/v2/…, and whichever credential you send, the call runs with exactly the rights of the user it resolves to.

Quick reference

Authenticating with an API token (recommended)

An API token is a value starting with dmapi_ that an administrator creates on the API Tokens screen (or a user creates for themselves under My Settings → API Tokens & Devices where the site allows it). Send it as a Bearer header on every request, exactly as issued, with no Base64 or other encoding:

curl https://yoursite.docmgt.com/rest/v2/authtest \

  --header "Authorization: Bearer dmapi_your_token_here"

A valid token returns the user's ID and username; an invalid, expired, or revoked token returns 401 with "Invalid or expired bearer token." Tokens are the right choice for anything unattended because they can be revoked individually, they can expire on a schedule, and no password is stored in your configuration. Plan for expiry: build your integration so a 401 is surfaced clearly (log it, alert on it) rather than silently retried, because an expired token never starts working again — someone must issue a new one.

Authenticating with a username and password

Standard HTTP Basic authentication works on every endpoint: Base64-encode username:password and send it as Authorization: Basic …. Every HTTP library does this for you when given a username and password.

curl https://yoursite.docmgt.com/rest/v2/authtest \

  --user "someuser:somepassword"

Two caveats. First, a site can turn on Require API tokens, after which every password-authenticated API call fails with 401 and the message "Password authentication is disabled for this site. Use an API token." — your integration should treat that message as a configuration problem, not a transient error. Second, password calls bypass the interactive protections of the web sign-in (multi-factor authentication, single sign-on), which is exactly why sites lock them out; prefer tokens from the start and you will never be affected.

Sessions: login and session GUIDs

If your integration makes many calls in a burst, you can sign in once and reuse the resulting session instead of sending the credential every time. GET /rest/v2/login with either credential returns the user's profile including a GUID; send that GUID as a Bearer header on subsequent calls. The session slides with use and expires after about a day of inactivity, after which calls return 401 and you simply log in again. This is optional — sending the token or Basic header on every call is also fine, and is the simpler pattern.

curl https://yoursite.docmgt.com/rest/v2/login --user "someuser:somepassword"

… response includes "GUID": "3f6b…"

curl https://yoursite.docmgt.com/rest/v2/records/123 \

  --header "Authorization: Bearer 3f6b…"

GET /rest/v2/authtest validates a credential without creating a session — useful for a configuration screen's "test" button. GET /rest/v2/gettoken returns a single-use, five-minute login token for handing a signed-in identity to another process; it is consumed on first use and is unrelated to dmapi_ API tokens.

Managing tokens over the API

Token management itself is available over REST for automation. POST /rest/v2/apitokens creates a token (administrators for any user; a non-admin for themselves when the site allows user-created tokens) and returns the raw token once in the response — it cannot be fetched again. GET /rest/v2/apitokens lists metadata (never the token value), with ?userId= and ?kind=Integration|Device filters for administrators. PATCH /rest/v2/apitokens/{id} renames and DELETE /rest/v2/apitokens/{id} revokes; users may manage their own tokens, administrators anyone's.

Errors and diagnostics

A failed credential always returns 401 with a JSON body carrying Status, Title, and Detail; read Detail — it distinguishes a bad password, a disabled account, an expired token, and a site that requires tokens. A 403 means the credential was valid but the user lacks rights to that operation. The WWW-Authenticate response header advertises which schemes the site currently accepts. Interactive exploration is easiest in the site's Swagger UI at /swagger, which supports both Basic and Bearer in its Authorize dialog.

TIPS

1. Default to API tokens — they survive the site turning on Require API tokens; passwords do not.
2. Send the dmapi_ token raw in the Bearer header; Base64-encoding it is the most common integration mistake.
3. Surface 401s loudly in unattended integrations — an expired or revoked token needs a human, not a retry loop.
4. Use /rest/v2/authtest for connection tests; it validates without side effects.
5. One token per integration and per machine, so any one of them can be revoked without collateral damage.

NOTE: Whatever credential you send, calls run with exactly the rights of the resolved user, and every action is attributed to that user in DocMgt's logs. Use a dedicated, minimally-privileged user for each integration.