A service account is a machine user configured to perform tasks within a Redox organization. Learn more about service accounts.
- 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.
- Log in to the dashboard.
- Click your username at the bottom of the navigation menu.
- From the user menu, select the Access control option.
- By default, the Users tab opens. Click the Service accounts tab.
- All existing service accounts for this organization appear in the table.
- Follow the steps to view service accounts.
- Click the New service account button.
- The Details page opens. Fill out the form:
- Name: Enter the service account name. This is the name that appears in the dashboard and with any audit events.
- (Optional) Description: Describe the purpose of this machine user.
- (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.
- 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.
- Click the Create button.
- Follow the steps to view service accounts.
- Click the row of the service account you want to manage.
- The Details page opens. Under the Roles section, click the Edit button.
- 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
- Click the Save button.
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.
- Follow the steps to view service accounts.
- Click the row of the service account you want to authenticate.
- Under the Public keys section, choose one of the following options to continue:
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 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.
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:
- To any of the Platform API endpoints: https://api.redoxengine.com/platform/{endpoint}. Each Platform endpoint has different requirements, path parameters, or request parameters. Explore each endpoint schema for their respective requirements.
- Via the Redox MCP. Learn how to access the Redox MCP server.
Access tokens don’t work on any of the Redox data model or FHIR® resource endpoints for service accounts.
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.
- Follow the steps to create a service account.
- Follow the steps to authenticate a service account.
- Update your system to authenticate the service account using the new OAuth API key.
- In the service account API requests:
- Change the clientID to that of the service account (under the Service account details section).
- 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.
- Confirm that the service account is receiving access tokens with the new API key.
- (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:
- Log in to the Redox dashboard.
- Click your username at the bottom of the navigation menu.
- From the user menu, select the User settings option.
- By default, the User info tab opens. Click the User API keys tab.
- 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.