API Authentication

Prima's REST API uses OAuth 2.0. Every request to the API must carry a JSON Web Token (JWT) obtained from your Prima server's token endpoint. This page covers setting up an API client, requesting and refreshing a token, and best practices for using it in an integration.

Note: This page covers authenticating API clients that read or write lab data. To configure how lab staff sign in to Prima itself (LDAP, Okta, Windows), see Server Configuration → Authentication.

Setting up an API client

API clients are created and managed from your internal Prima website (typically something like 'https://prima.your-workplace-website.com'), under Admin → API Clients. Each client represents one integration and gets its own credentials, scopes, and token settings.

Go to Admin → API Clients and create a new client.
Give it a Client Name (for your own reference) and a Client ID.
Save the client, then add a Client Secret from the client's edit page. The secret is shown once — store it somewhere secure.
Choose the Grant Type(s) the client is allowed to use (see below).
Choose the Scopes the client needs: read-only, or read/write.
If the client will write data (create or modify cases, specimens, etc.), assign it a Service User. Prima attributes the records it creates or edits to this user, which keeps your audit trail meaningful. Read-only clients can leave this blank.

Refresh tokens

If an integration needs to stay authenticated over a long period without holding onto the client secret for every renewal, enable refresh tokens on the client:

Use Refresh Tokens — grants the client the offline_access scope, so a refresh token is returned alongside the access token.
Refresh Token Usage — One-Time Only issues a new refresh token every time one is used, and invalidates the old value; Re-Use allows the same refresh token to be used repeatedly until it expires.
Refresh Token Expiration — Absolute expires a fixed time after issue; Sliding extends the expiration each time the token is used, up to a maximum lifetime. Defaults are 30 days absolute / 15 days sliding.

Choosing a grant type

Grant type	Use for
`client_credentials`	Recommended for server-to-server integrations. The client authenticates with its own ID and secret — no end-user login is involved.
`refresh_token`	Exchanging a refresh token for a new access token without repeating the original grant.
`password`	Resource owner password grant, tied to a specific Prima user login. Supported for backward compatibility; prefer `client_credentials` for new integrations.
`authorization_code`	Interactive applications where a person logs in and grants consent (e.g. a browser-based tool). Requires a Redirect URI configured on the client.

Requesting a token

Send a POST to your Prima server's token endpoint with the client's credentials:

POST https://your-prima-server/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id={ClientId}
client_secret={ClientSecret}
scope=api_read_all api_write_all

A successful response looks like:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Include offline_access in the requested scope (and enable refresh tokens on the client) to also receive a refresh_token in the response.

Refreshing a token

Before the access token expires, exchange the refresh token for a new one rather than repeating the original grant:

POST https://your-prima-server/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
client_id={ClientId}
client_secret={ClientSecret}
refresh_token={RefreshToken}

Warning: If the client's Refresh Token Usage is set to One-Time Only, the response contains a new refresh_token that replaces the one just used. Save it — the old value stops working.

Using the access token

Include the access token on every API request as a bearer token:

GET https://your-prima-server/api/v2/Case
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Access tokens are short-lived (one hour by default). Cache the token and reuse it for the duration of its lifetime instead of requesting a new one before every call — request a new one once it's close to expiring, or use the refresh token flow if it's configured.

Best practices

Prefer client_credentials over password for server-to-server integrations — it doesn't tie the integration to an individual user's login.
Request only the scopes you need. If an integration only reads data, don't request write access.
Treat the client secret like a password. Store it in a secrets manager or protected configuration, not in source control. A client can hold more than one secret at a time, so you can add a new one and remove the old one to rotate without downtime.
Cache and reuse access tokens until shortly before they expire, instead of requesting a new one for every API call.
Assign a Service User to write clients so records created or modified by the integration are attributed correctly.
Test before you integrate. Use the Test Authentication page on your Prima server (under Docs) to generate a token interactively and confirm the client is configured correctly before writing code against it.

Troubleshooting

401 Unauthorized when requesting a token: Double check the client_id and client_secret, and confirm the grant type being used is allowed on the client.
401 Unauthorized calling the API with a token: The token may have expired, or the requested scope may not include what the endpoint requires.
403 Forbidden on write requests: The client's scopes may be missing write access, or the client doesn't have a Service User assigned.
Refresh token no longer works: Refresh tokens expire (30 days by default) and, if One-Time Only usage is configured, are replaced with a new value every time they're used — reusing an old one fails.

Example clients

An example .NET client is available at github.com/Fortelinea/PrimaRESTExampleClient. It demonstrates the resource owner password grant used by older (V1) integrations; new integrations should follow the client_credentials pattern described above instead.