Manage service accounts

Service accounts let an application call ​ValidMind with its own identity instead of a person’s credentials. Each service account belongs to one organization and is tied to a client-credentials application in your identity provider.

An application can sign in as a service account in two ways:

• With an access token that your identity provider issues to the application through the client-credentials grant. This works once you verify the account’s client.
• With a ​ValidMind API key and secret, if you create one together with the account.¹

¹ Public REST API

Prerequisites

• You are logged in to ValidMind.
• You have an administrator role, such as Customer Admin.² Only users with an administrator role see the Service Accounts page and can create, verify, disable, enable, or rotate service accounts.
• Your identity provider administrator created a client-credentials application for the service and shared its client ID with you.
• To sign in with access tokens, your ​ValidMind deployment administrator configured client-credentials sign-in for your identity provider. Service accounts that only use a ​ValidMind API key don’t need this.

² Manage roles

View service accounts

1. In the left sidebar, click Settings.

2. Under Integrations, select Service Accounts.

Each service account shows its name, email address, client ID, and identity provider. Tags show whether the account is enabled or disabled, and whether its client is verified.

Create service accounts

1. In the left sidebar, click Settings.

2. Under Integrations, select Service Accounts.

3. Click Create Service Account.

4. Fill in the details:

   • Name — Enter the name people see in groups and assignee lists.
   • IdP Client ID — Enter the client ID of the application in your identity provider. This is the client ID that appears in the access tokens the application receives.
   • Email — Once you enter the client ID, this field is prefilled with svc+<client-id>@service-account.invalid. Every account needs an email address, but sign-in doesn’t use it. You can replace it with another address that no other user in ​ValidMind has.
   • Roles (optional) — Select the organization roles the account needs if the access tokens from your identity provider don’t include roles.
   • Create a ValidMind API key (optional) — Select to issue a ​ValidMind API key and secret with the account. If you skip this, you can’t add a key to the account later.

5. Click Create Service Account.

6. If you selected Create a ValidMind API key, copy the credentials before you close the dialog:

   1. Next to API Key, click Copy and store the key in a secure location.

   2. Next to API Secret, click Copy and store the secret in a secure location.

   3. Click Done.

ImportantYou can view the API secret only once.

​ValidMind doesn’t show the secret again after you close the dialog. Keep the API key as well, since you need it to rotate the credentials later.

New service accounts are unverified. Before the application signs in with an access token, verify the account’s client.

To change the roles of a service account after you create it, use the User Directory.³

³ Manage users

Verify service account clients

Verification proves that your organization holds the client’s secret, so no other organization can use the same client ID. You verify each service account once. API keys don’t need verification.

You can verify a client only after your ​ValidMind deployment administrator configures client-credentials sign-in for your identity provider.

1. Request an access token from your identity provider for the application, using the client-credentials grant with the application’s client ID and secret. Use your provider’s token URL and scope, then copy the access_token value from the response.

   Access tokens are short-lived, often an hour or less. Request a fresh token right before you verify.

2. In the left sidebar, click Settings.

3. Under Integrations, select Service Accounts.

4. Hover over the service account you want to verify.

5. When the menu appears, click it and select Verify Client.

6. Paste the token into Access Token.

7. Click Verify Client.

The service account now shows as verified, with the date. ​ValidMind checks the token once and doesn’t store it.

If verification fails, the dialog shows the reason, for example that the token is for a different client or has expired. Request a new token and try again.

NoneHow do I request an access token?

The exact request depends on your identity provider. A typical request looks like this, with the placeholders replaced by your provider’s token URL, the application’s client ID and secret, and the scope your provider requires:

curl -s -X POST "https://<your-idp>/oauth2/<server>/v1/token" \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials&scope=<scope>"

Copy the access_token value from the response.

Disable or enable service accounts

When you disable a service account, ​ValidMind rejects both its access tokens and its API key until you enable it again. You can’t delete service accounts, so disable an account that is no longer in use.

Disable service accounts

1. In the left sidebar, click Settings.

2. Under Integrations, select Service Accounts.

3. Hover over the service account you want to disable.

4. When the menu appears, click it and select Disable.

5. Click Disable Service Account to confirm.

Enable service accounts

1. In the left sidebar, click Settings.

2. Under Integrations, select Service Accounts.

3. Hover over the disabled service account you want to enable.

4. When the menu appears, click it and select Enable.

5. Click Enable Service Account to confirm.

Rotate service account API keys

Rotating replaces the API key and secret of a service account. You can rotate only a key that was created together with the account, and you need the current API key to do so.

1. In the left sidebar, click Settings.

2. Under Integrations, select Service Accounts.

3. Hover over the service account whose key you want to rotate.

4. When the menu appears, click it and select Rotate API Key.

5. Paste the account’s API key into Current API Key.

6. Click Rotate API Key.

7. Copy the new credentials before you close the dialog:

   1. Next to API Key, click Copy and store the key in a secure location.

   2. Next to API Secret, click Copy and store the secret in a secure location.

   3. Click Done.

​ValidMind stops accepting the old key and secret right away. Update every application that used them.

Service accounts in the User Directory

Service accounts appear in the User Directory together with the people in your organization.⁴ A key icon next to the name marks a service account. Hover over the icon to see the Service account tooltip.

⁴ Manage users

In the User Directory, you can change the roles of a service account as you would for any user. To disable a service account, use the Service Accounts page instead.

Service accounts also appear in other places where you select users, such as groups, stakeholder fields, and assignee lists.