Manage service accounts

Last updated: Nov 4, 2026
IMPLEMENTATION
HEALTH TECH VENDOR
DEVELOPER
SUPPORT

A service account is a machine user configured to perform tasks within a Redox organization. Learn more about service accounts.

Definitions

Prerequisites

  • A user must be assigned to either an organization owner or admin role to create service accounts, as well as manage its role assignments. Learn more about user roles.
  • A user must be assigned to an engineer role to create or authenticate API keys for a service account. Learn about user roles.
    • If you choose option 2 for creating a user-level API key, you must have an existing public key. This can be either a JWKS URL or or JWKS entry.
  • For migrating to a service account, your organization must already have an existing MCP or Platform API integration using a user-level API key.

View service accounts

  1. Log in to the dashboard.
  2. Click your username at the bottom of the navigation menu.
  3. From the user menu, select the Access control option.
  4. By default, the Users tab opens. Click the Service accounts tab.
  5. All existing service accounts for this organization appear in the table.

Create a service account

  1. Follow the steps to view service accounts.
  2. Click the New service account button.
  3. The Details page opens. Fill out the form:
    1. Name: Enter the service account name. This is the name that appears in the dashboard and with any audit events.
    2. (Optional) Description: Describe the purpose of this machine user.
    3. (Optional) Groups: Select a user group the service account should belong to. This applies the group’s pre-selected organization and environment roles automatically to the new service account.
    4. Roles: Select the organization role and any environment roles for the individual service account. If you selected a group, you must select an organization role, but the environment roles are option if you want to use the group roles.
  4. Click the Create button.

Manage a service account’s role assignments

  1. Follow the steps to view service accounts.
  2. Click the row of the service account you want to manage.
  3. The Details page opens. Under the Roles section, click the Edit button.
  4. Click the Role drop-down then select the role you want to assign to the service account in the organization or any of the environments.
    Multiple role assignments

    A user might have multiple role assignments if they’re both part of a user group and have been assigned an individual role assignment. If they have multiple roles, they have the permissions of all roles assigned to them.

  5. Click the Save button.

Authenticate a service account

Step 1: Generate or provide a public key

Before a service account can authenticate an API request, it must have an API key with a private/public key pair. There are a few options for this step:

  • Option 1: Generate a private/public key pair in the Redox dashboard.
  • Option 2: Provide your public key (i.e., JWKS entry) and store your own private key.
  • Option 3: Provide a JWKS URL for your public key and store your own private key.

The navigation steps are the same, but there are different steps for each method provided below.

  1. Follow the steps to view service accounts.
  2. Click the row of the service account you want to authenticate.
  3. Under the Public keys section, choose one of the following options to continue:

Step 2: Request and store an access token

Next, the service account must request an access token with an auth request. Follow the OAuth API key instructions for requesting and storing an access token.

A service account request requires these differences to the auth request, though:

  • The scope parameter is required. Omitting this parameter returns invalid_scope.
    • Set scope to platform_access to use the already defined permissions of the service account’s assigned user role(s). Learn about user roles.
    • Set scope to individual permission IDs (see table below) to limit the service account’s permissions further than its assigned roles. You can't set higher permissions than its assigned role, though. For example, a service account assigned to an observer role can't view log payloads by setting scope: env:log:view-payload.
      • Separate multiple scopes with spaces, not commas.
      • Wildcards (e.g., env:*) aren't accepted.

Permission IDs for setting scope

Permission ID

Observer

Support

Engineer

env:alert:view

View traffic alert rules within an environment, as well as any Redox system alerts.

X

X

X

env:alert:manage

Create, edit, or delete traffic alert rules within an environment.

X

X

env:connection: view

View an organization’s connections with the related details for each subscription.

X

X

X

env:connection: manage

Create or delete subscriptions.*

X

env:connectivity:view

View an organization’s sources, destinations, and related auth credentials.

X

X

X

env:connectivity:manage

Create, edit, and delete an organization’s sources, destinations, and related auth credentials.

X

env:devtools:send

Use Redox dashboard testing tools to send test messages with an environment’s configured sources or receiving test messages to configured destinations.

X

env:log:view-metadata

Search and view results with log metadata, errors, and retries in an environment.

X

X

X

env:log:view-payload

Search and view results with log metadata, payloads, errors, retries, and log inspector. Payloads may contain confidential data.**

X

X

env:log:retry

Initiate a new attempt for an existing log, whether failed or successful.

X

X

env:operation:view

View any data processing operations in an organization (i.e., filters, translations, config modifiers).

X

X

X

env:operation:manage

Create, edit, and delete any data processing operations in an organization (i.e., filters, translations, config modifiers).

X

X

env:processor-run:view-metadata

Search and view results with processor run metadata.

X

X

X

env:processor-run:view-payload

Search and view results with processor run metadata, payloads, parameter values, errors, retries, and inspection. Payloads and parameter values may contain confidential data.***

X

X

* This is an open beta feature, so talk to your Technical Account Manager to enable. Learn more about creating subscriptions.

** You can search log payloads in both the Redox dashboard and the Redox Platform API. However, the contents of log payloads are only available in the dashboard. Platform API responses only contain log metadata for matching log results.

*** Processors are an open beta feature. Learn more about processors.

Step 3: Initiate API requests

Access is a combination of the service account’s assigned user roles and requested scopes. A disabled or deleted service account is immediately rejected, even if an access token was already issued.

After getting an access token, an active service account is ready to initiate API requests:

Access tokens don’t work on any of the Redox data model or FHIR® resource endpoints for service accounts.

Migrate to a service account

Service accounts with their own API keys are a more flexible alternative for your MCP or Platform API integrations currently using user-level API keys. It also removes the dependence on a human user.

Migrating to a service account can be performed with zero downtime.

Follow these instruction if your organization has an existing MCP or Platform API integration with user-level API key that you want to migrate to a service account.

  1. Follow the steps to create a service account.
  2. Follow the steps to authenticate a service account.
  3. Update your system to authenticate the service account using the new OAuth API key. 
    1. In the service account API requests:
      1. Change the clientID to that of the service account (under the Service account details section).
      2. Add the required scope parameter. This should be set to platform_access to use the service account’s assigned user roles, or set to specific permission scopes, if needed.
    2. Confirm that the service account is receiving access tokens with the new API key.
  4. (Optional) The user-level API key that the MCP or Platform API integration previously used continues working. You can choose to keep or delete it. If you choose to delete it, follow these steps:
    1. Log in to the Redox dashboard.
    2. Click your username at the bottom of the navigation menu.
    3. From the user menu, select the User settings option.
    4. By default, the User info tab opens. Click the User API keys tab.
    5. The User API keys page opens with any existing user-level API keys. Find the one the service account was using and click the three-dots icon in its row, then the Delete option.

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.