# Manage service accounts

A <u>service account</u> is a machine user configured to perform tasks within a Redox organization. [Learn more about service accounts](/basics/managing-access-for-your-redox-organization/what-are-redox-organizations-users-and-service-accounts).

## Definitions

<details>
<summary>Organization role</summary>

A user’s <u>**organization role**</u> determines their administrative capabilities and access within a Redox organization. There are three types of organization roles:

- owner
- admin
- member

When a user is invited to an organization, they’re assigned to a <u>**member**</u> organization role by default.
A user’s organizational role doesn’t impact their assigned environment role.

</details>

<details>
<summary>Environment role</summary>

A user’s <u>**environment role**</u> determines their technical capabilities and access within an environment of a Redox organization. There are three types of environment roles:

- observer (default role in <u>**production**</u> environments)
- support
- engineer (default role in <u>**staging**</u> and <u>**development**</u> environments)

Some of these roles have overlapping permissions and capabilities, but usually for different purposes within the environment. A user’s environment role doesn’t impact their assigned organization role.

</details>

## Prerequisites

- A user must be assigned to either an <u>**organization owner**</u> or <u>**admin**</u> role to create service accounts, as well as manage its role assignments. [Learn more about user roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles-and-groups).
- A user must be assigned to an <u>**engineer role**</u> to create or authenticate API keys for a service account. [Learn about user roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles-and-groups).
  - If you choose option 2 for creating a user-level API key, you must have an existing <u>**public key**</u>. This can be either a <u>**JWKS URL**</u> or or <u>**JWKS entry**</u>. 
- _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 <u>Users</u> 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 <u>Details</u> 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 <u>Details</u> page opens. Under the <u>Roles</u> 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:

- <u>Option 1</u>: Generate a private/public key pair in the Redox dashboard.
- <u>Option 2</u>: Provide your public key (i.e., JWKS entry) and store your own private key.
- <u>Option 3</u>: 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 <u>Public keys</u> section, choose one of the following options to continue: 

<details>
<summary>Option 1: Generate keys in the Redox dashboard</summary>

Follow these steps to generate a new key pair (i.e., private and public keys) in the Redox dashboard. Generating gives you a private key that you store and a JWKS entry for the public key that Redox stores.

1. From the <u>Method</u> drop-down, select the **Generate or provide keys** option, then click the **Generate a key pair** tab. 
2. Click the **Generate keys** button. 
3. The <u>Private key</u> and <u>Public key</u> fields populate. Copy and store these values by clicking the **format** (i.e., JSON, PEM) you want, then selecting the **Copy** or **Download** options. 
_This is the only time you_’_ll see the private key in the Redox dashboard, so make sure to copy or download, then store it securely._ 
4. If using Postman, click the **Download Postman environment** button to use our environment for sending Platform API requests.
5. Click the **Create** button. 
_The keys aren_’_t stored until you save them._ 
6. After the keys are saved, the newly generated public key automatically populates the JWKS entry under the  <u>Provide your own</u> tab. On the <u>User API keys</u> tab, the <u>Public key</u> column populates with `JWKS with 1 key(s)`.

</details>

<details>
<summary>Option 2: Provide your public key (JWKS entry)</summary>

If you already have a key pair, you can provide the public key to Redox and store your private key. The <u>JSON Web Key Set</u> (<u>JWKS</u>) entry is the actual JSON entry for the public key. 

1. From the <u>Method</u> drop-down, select the **Generate or provide keys** option.
2. Click the **Provide your own** tab. 
3. Paste the **JWKS entry** in the field provided. 
4. Click the **Save** button. _The public key isn't stored until you save._ 


</details>

<details>
<summary>Option 3: Provide an existing public key </summary>

If you already have a key pair, you can provide the public key to Redox and store your private key. The <u>JSON Web Key Set</u> (<u>JWKS</u>) URL publicly exposes the public key you use for generating the signed assertion. The URL can be internal to your servers or somewhere like a GitHub Gist. If you use this URL, Redox fetches the `kid` property in the JWT to find the right public key.  

1. From the <u>Method</u> drop-down, click the **Provide a JWKS URL** option. 
2. Paste the **JWKS URL** in the field provided. 
3. Click the **Save** button. _The public key isn't stored until you save._

</details>

### 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 ](https://docs.redoxengine.com/permalink/0CKpMIghEgSam9nJuzyXe#send-an-auth-request)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](/basics/managing-access-for-your-redox-organization/what-are-user-roles-and-groups).
  - Set `scope` to individual <u>permission IDs</u> (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

| <u>Permission ID</u> | 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_](/how-to-use-redox/manage-your-redox-setup/create-a-subscription)_._

_\*\* 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_](/basics/data-exchange-with-redox/orchestrate-your-unique-data-workflows)_._

### 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:

- 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](https://docs.redoxengine.com/permalink/platform-api-landing-page) for their respective requirements.
- Via the Redox MCP. [Learn how to access the Redox MCP server](/how-to-use-redox/access-the-redox-mcp-server).

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 instructions 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 <u>Service account details</u> 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 <u>User API keys</u> 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.
