Skip to main content

Client Applications

A client application is what your integration signs in as. Each one has a Client ID, one or more client secrets, and a set of roles that decide what it can do in the API. You exchange the Client ID and a secret for a bearer token as described in Authentication.

You manage your applications yourself in the portal. ClaimRev never sends a secret by email, and no one at ClaimRev sees the secrets you generate.

Where to find it​

In the portal, open Practice Admin, then API Integrations, then Client Applications.

Your portal role needs API integration access to see this page. If API Integrations is missing from Practice Admin, ask your practice administrator to add it to your role, or contact ClaimRev support.

Test and production are separate. Applications, Client IDs and secrets created in testportal.claimrev.com only work against the test environment, and the same is true for production. Repeat these steps in each portal you integrate with.

The page lists each application with its Client ID (with a copy button), the status of its secret, how many roles it has, and an actions menu.

Getting a client application​

If your account already has one​

ClaimRev usually sets up the first application when your account is provisioned. If it appears in the list:

  1. Click the copy button next to the Client ID.
  2. If the Secret column says No secret yet, click Generate secret and follow Generating a secret below.
  3. If it already has a secret but you do not have the value, you cannot view it again. Click Rotate secret to issue a new one.

Requesting a new application​

Use a separate application for each system that calls the API (for example, your EMR integration and a reporting tool), so you can rotate or disable one without affecting the other.

  1. Click Request application at the top of the page.
  2. Enter an Application name you will recognize later, such as the vendor or system name.
  3. Optionally add a Description and what the application will be used for. This is shown to the ClaimRev reviewer.
  4. Click Submit request.

What happens next depends on the environment:

  • Test: requests are normally approved immediately. The application appears in the list straight away with No secret yet.
  • Production: ClaimRev reviews the request first. Until then it is listed under Requests below the table as Pending. Once approved, it moves into the main list. If a request is declined, the reason is shown on the request.

A new application has no secret. Generate one next.

Generating a secret​

  1. Click Generate secret on the application's row and confirm.
  2. The new secret is shown once. Click Copy and store it in your secret manager or deployment configuration before closing the dialog.
  3. Click Done.

If you close the dialog without copying the secret, it cannot be recovered. Generate another one and revoke the lost one from Manage secrets.

Secrets are valid for two years. The expiry date is shown under the secret status.

Setting the application's roles​

Roles decide which endpoints and data the application can reach. They are the same roles you can assign to a person on your account.

  1. Open the actions menu (⋮) on the application's row and choose Manage roles.
  2. Pick one or more roles and click Add role(s). Remove a role with the delete button next to it.

An application with no roles authenticates successfully but receives 403 from most endpoints. Grant only what the integration needs.

Rotating a secret​

Rotation issues a new secret without invalidating the old one, so you can switch over with no downtime.

  1. On the application's row, click Rotate secret and confirm.
  2. Copy the new secret from the dialog. It is shown once.
  3. Deploy the new secret to your integration.
  4. Verify it: request a token with the new secret and make a call such as GET /api/UserProfile/v1/GetDefaultAccount (see Authentication).
  5. Back in the portal, open the actions menu (⋮) and choose Manage secrets.
  6. Click Revoke on the old secret. Secrets generated in the portal are named with the date they were created, and the new one expires two years from today, so the old one has the earlier dates.

Until you revoke the old secret, both work. Do not skip step 6: an old secret left in place is still a valid credential.

Revoking can take a few minutes to take effect everywhere, so a token request with the revoked secret may briefly still succeed.

Expiry reminders​

The Secret column shows Expires in N day(s) once a secret is within 30 days of expiring, and Expired after that.

During that window, users on your account see a reminder when they sign in to the portal. Users with API integration access get a Manage secrets button that takes them to this page. Other users are asked to contact your IT administrator.

When a secret expires, token requests using it fail with 401 (invalid_client) and your integration stops working until you deploy a new one. Rotate before the expiry date.

If a secret is compromised​

  1. Rotate the secret and deploy the new one.
  2. Revoke the compromised secret right away in Manage secrets. Do not wait for the full rollout if the old secret may be in the wrong hands.
  3. Contact ClaimRev support so we can review activity on the application.

If you need to stop the application entirely while you investigate, use Disable application (below).

Disabling an application​

Choose Disable application from the actions menu to stop an application from calling the API immediately. Its Client ID, secrets and roles are kept, and Re-enable application turns it back on with its existing secret.

You cannot generate or rotate a secret while an application is disabled. To remove an application permanently, contact ClaimRev support.

Client Connect​

The Client Connect page also shows a Client ID and secret. It shows only one application for the account, so if you have more than one, use Client Applications to see and manage all of them.