Overview

A service account is a special type of user account in Appian that is a member of the Service Account system group. They are used in portals to authenticate back to Appian. This allows portal users to access information and processes in Appian without having to log in. Using service accounts in this way keeps your Appian environment secure while ensuring your portal users have access to the information and processes that are important to them.

You need to give service accounts the appropriate permissions to act on behalf of the portal. See Required permissions for portal service accounts for what permissions to grant depending on the portal use case.

The page provides information about using service accounts in portals.

Creating service accounts

Only system administrators can create service accounts. They have a few different options for creating service accounts:

• From the Service Access section in the portal object.
• When creating an API key in the Admin Console.
• By creating a user and adding it to the Service Accounts system group.

Required permissions for portal service accounts

The permissions you give your service account will depend on the use cases for your portal. This table outlines the appropriate permissions to give to the service account based on what your portal does.

You don't need to give access to every object used in your portal. Only the objects listed below.

If your portal…	Grant the following permissions…
Queries records	Viewer permission to the record type. Be sure to configure any necessary record-level security as well to determine who can see which records.
Adds, updates, or deletes records	Viewer permission to the record type. Be sure to configure any necessary record-level security as well to determine who can see which records. Initiator permissions to the process model. See Start Process Smart Service for more information on the difference between Initiator and Viewer permissions.
Starts a process	Initiator or Viewer permissions to the process model, along with any other permissions required for the smart services used in the process model. See each smart service page for the permissions needed. If the portal needs access to process model properties, process instance properties, or process variable values, give the service account Viewer permissions. See Start Process Smart Service for more information on permissions needed.
Uploads documents	Editor permissions to the document folders that files will be uploaded to.
Displays or downloads documents	Viewer permissions to the document folders where the documents are stored.
Queries or writes data to a publicly-accessible external database	Viewer permissions to the data store for the external database.
Queries or writes data using a CDT	Grant the service account that is tied to the API key Viewer permissions to the web API and data store.
Uses a custom integration to use partially compatible capabilities	Grant the service account that is tied to the API key Viewer permissions to the web API and any other design object that the portal needs access to.

See Create a Portal for instructions on how to give the portal service account appropriate permissions.

Making sure your service account has access to the right data

Using service accounts prevents you from unintentionally exposing the wrong data or documents in a portal. As such, we recommend that you only grant the service accounts permissions to the records, documents, and processes that are needed for the portal.

As a best practice, avoid setting Default (All Other Users) to have Viewer permission on your record types. Service accounts are considered "users" for this setting, which means that this grants viewer access to all service accounts as well as all logged-in users.

You can view and update the record type permissions that the service account can currently access directly from the portal object. Use the View record type permissions for the service account link in the Service Access section to make sure the portal service account:

• Has at least Viewer permissions to all of the record types used in your portal.
• Does not have access to record types that are not used in your portal.

To add permissions to a record type that is not in this list, go to the security settings for the record type.

That being said, portals will only expose data or start processes that are directly called in an interface. Even if the service account has permission to other record types or processes, if the developer does not directly call the record type or process in the portal, they will not be accessible from the portal.

Setting up service accounts in other environments

Before you deploy a portal to different environments, create the service account in each environment with the same username and group membership. To learn more, see deploying a portal.

Service accounts used for API keys

Service accounts are also used for web API authentication. When you set up an API key in the Admin Console, you tie the API key to a service account. If you are using web APIs for your portal, you can use the same service account that is tied to your API key to grant access to the records, documents, and processes used in your portal.

The service account that you choose in the portal object is only used to grant access to the objects that the portal needs. If you use a different service account for an API key in your portal, you don't need to add the service account to the portal object.