Authentication & access

How OmniValVMS authenticates requests today, and what programmatic API access will look like.

Every OmniValVMS API request must be authenticated. This page describes the authentication model the platform uses today — no placeholder keys, no sandbox that doesn't exist.

How authentication works today

OmniValVMS uses bearer-token authentication. You sign in with your account credentials and receive an access token, which you then send on every subsequent request.

  1. Sign in

    Exchange your client credentials for an access token.

  2. Send the token on every request

    Include the token in the Authorization header as a bearer token.

  3. Refresh before it expires

    Access tokens are short-lived. Use the refresh endpoint to get a new one without re-entering credentials.

Authorizing a request

Once you have a token, send it as a bearer token:

GET /api/clients/{clientId}/orders HTTP/1.1
Host: api.omnivms.com
Authorization: Bearer <your-access-token>
Accept: application/json
Authorization is checked on every request

Beyond authentication (who you are), OmniValVMS enforces authorization (what you're allowed to do) on every endpoint, scoped to your client and your role. A valid token for one client cannot access another client's data.

Tokens expire — refresh them

Access tokens are intentionally short-lived. When a request returns 401 because the token has expired, call the refresh endpoint to obtain a new access token, then retry the original request once.

For reads and clearly idempotent operations, retry once after refresh. For P0 state-changing actions such as activation, assignment, QC/revision, payments, and UCDP/EAD submission, reload the order and check history before replaying the write.

Do not retry a 401 without refreshing first — repeatedly sending an expired or invalid token will keep failing.

Password & account recovery

The platform also exposes the flows behind account recovery, which you may need when onboarding users:

Programmatic API access

Coming soon

A self-service developer portal with issued API keys and a dedicated sandbox environment is on our roadmap. It does not exist yet.

Until it ships, authenticate with the sign-in flow above against the live platform. These docs will be updated the moment API keys and a sandbox are available — we won't ask you to use credentials that aren't real.

When programmatic access lands, expect:

  • API keys you can create, rotate, and revoke yourself (shown once, hashed at rest)
  • A sandbox with synthetic data, isolated from production, where no real orders or payments occur
  • Usage and audit logs for every key

Next

With access understood, set up your organization: