Manage service accounts

A service account is an AI agent (or other machine user) that operates on a specific user’s behalf. 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.

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.

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.

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.

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:

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 and must have the scope set to platform_access to include all permissions in the service account's assigned user role(s). Alternatively, the scope can be set to individual permission scopes (granted by role assignments).
  • OpenID-style scopes are refused with invalid_scope.

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.

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.