Web API Authentication

Purpose

The Web API Authentication page in the Admin Console allows you to manage API keys and OAuth 2.0 clients, which can be used to invoke Appian Web APIs.

Access

To access the Web API Authentication page, go to the Admin Console. Then, in the left navigation menu, under Authentication, click Web API Authentication.

Settings

The Web API Authentication page contains the following settings.

API keys

The API Keys tab allows you to create and manage API keys and Service Accounts, which can be used to invoke Appian Web APIs. This page allows you to:

• Create a new API key and/or service account.
• Deactivate and reactivate API keys.
• Permanently delete API keys.

Creating an API key

To create a new API Key:

1. In the Admin Console, go to the Web API Authentication page.
2. On the API Keys tab, click Create.
3. Enter a unique Description.
4. Select a Service Account to associate with the key. To create a new service account:
   • Click Create Service Account .
   • Enter a username and click CREATE.

   Note:  "Service Account" will automatically be added to the end of the service account name. See Service accounts.

5. Click CREATE.

   

6. Copy the API Key and store it externally. Appian will never show the value of the API key a second time.
7. Repeat these steps in each environment, making sure the following are the same in each environment:
   • API key Description.
   • Service account Username.
   • Service account permissions and group membership.

Invalidating API keys

There are three ways to invalidate an API key:

• Delete an API key: This option is permanent. Once an API key has been deleted, it can never be restored.
• Deactivate an API key: For something more temporary, you can deactivate an API key. Inactive API keys can be reactivated in the future to make them work again.
• Remove the associated service account from the Service Accounts system group: This will cause all API keys and OAuth 2.0 clients associated with the service account to stop working. However, if the service account is placed back in the Service Accounts system group, the associated keys and clients will start working again.

Appian OAuth 2.0 Clients

The Appian OAuth 2.0 Clients tab allows you to create and manage OAuth 2.0 Clients and Service Accounts, which can be used to invoke Appian web APIs with the OAuth 2.0 Client Credentials grant. This page allows you to:

• Create a new Appian OAuth 2.0 client and/or service account.
• Deactivate and reactivate Appian OAuth 2.0 clients.
• Permanently delete Appian OAuth 2.0 clients.

Creating an Appian OAuth 2.0 Client

To create a new Appian OAuth 2.0 client:

1. In the Admin Console, go to the Web API Authentication page.
2. Go to the Appian OAuth 2.0 Clients tab.
3. Click Create.
4. Enter a unique Description.
5. Select a Service Account to associate with the client. To create a new service account, click Create Service Account and enter a username.

   Note:  "Service Account" will automatically be added to whatever username you enter. See Service accounts.

   

6. Copy the Client ID, Client Secret, and Token Request Endpoint values and store them externally. Appian will never show the value of the Client Secret a second time, so that value is particularly important to copy.

Managing Appian OAuth 2.0 Clients

There are three ways to invalidate an Appian OAuth 2.0 client:

• Delete an Appian OAuth 2.0 client: This option is permanent. Once a client has been deleted, it can never be restored.
• Deactivate an Appian OAuth 2.0 client: For something more temporary, you can deactivate an OAuth 2.0 client. Inactive OAuth 2.0 clients can be reactivated in the future to make them work again.
• Remove the associated service account from the Service Accounts system group: This will cause all API keys and OAuth 2.0 clients associated with the service account to stop working. However, if the service account is placed back in the Service Accounts system group, the associated keys and clients will start working again.

Mutual TLS

Mutual TLS lets you enforce two-way authentication between clients and Appian when clients invoke web APIs. The Mutual TLS tab lets you upload and manage the trusted client certificates that will be used in the authentication process. The main view of the tab is a grid view of all the client certificates in the system.

This feature is available only in some Appian Cloud environments when the following criteria are met:

• The web APIs must be available on the public internet.
• Inbound VPN is not enabled.
• Inbound PrivateLink is not enabled.

Contact Appian Support for further questions about enabling mTLS for your site.

Adding a client certificate

Client certificates must be uploaded to Appian for web API requests to use mutual TLS. You can upload a maximum of 250 client certificates.

To upload a new client certificate:

1. Click Add Trusted Client Certificate.
2. On the Add New Client Certificate dialog, select and upload the PEM file.
3. Click Upload.

Deleting a client certificate

If a certificate expires or needs to be removed for security reasons, you can delete it on the Mutual TLS tab.

To delete a client certificate:

1. On the row of the certificate you want to remove, click the Delete icon.
2. On the Delete Certificate? dialog, click Delete.

Third-Party OAuth 2.0 Clients

The Appian OAuth 2.0 Clients tab allows you to create and manage OAuth 2.0 Clients and Service Accounts, which can be used to invoke Appian web APIs with the OAuth 2.0 Client Credentials grant. This tab allows you to:

• Add a new third-party OAuth 2.0 client or service account.
• Deactivate and reactivate third-party OAuth 2.0 clients.
• Permanently delete OAuth 2.0 clients.

Adding a Third Party OAuth 2.0 Client

To add a new third-party OAuth 2.0 client:

1. In the Admin Console, go to the Web API Authentication page.
2. Go to the Third-Party OAuth 2.0 Clients tab.
3. Click Add.
4. Enter a unique Description.
5. Enter the Client ID that the OAuth 2.0 provider will send in the access tokens for this client.
6. Enter the Client ID Mapping. This is the key that will be used for the claim containing the client ID in the access tokens for this client.
7. Select the Public Key Method that will be used.
   • If you select JWKS URI, you will need to enter the JWKS URI that returns the JWK Set to verify access token signatures for this client.
   • If you select JWK File Upload, you will need to upload the JWKS Public Key file provided by the OAuth provider to verify access token signatures.
8. Enter the Issuer Claim (iss) value that the OAuth 2.0 provider will send in the access tokens for this client.
9. Enter the Audience Claim (aud) value that the OAuth 2.0 provider will send in the access tokens for this client.
10. Select a Service Account to associate with the client.
    • To create a new service account, click Create Service Account and enter a username. "Service Account" will automatically be added to the username you enter. Learn more.

11. Click ADD.

    

Once the third-party OAuth 2.0 client has been configured properly, Appian web APIs can be called using access tokens from the OAuth provider that match the values of the claims that you entered. These access tokens will be used to call web APIs in the context of the selected service account.

Managing Third-Party OAuth 2.0 Clients

There are three ways to invalidate an Appian OAuth 2.0 client:

• Delete a third-party OAuth 2.0 client: This option is permanent. Once a client has been deleted, it can never be restored. It must be manually added again.
• Deactivate a third-party OAuth 2.0 client: For something more temporary, you can deactivate an OAuth 2.0 client. Inactive OAuth 2.0 clients can be reactivated in the future to make them work again.
• Remove the associated service account from the Service Accounts system group: This will cause all API keys and OAuth 2.0 clients associated with the service account to stop working. However, if the service account is placed back in the Service Accounts system group, the associated keys and clients will start working again.

Service Accounts

If you need to create a new service account, you can easily do so by clicking the plus icon to the right of the Service Account picker on the API key creation modal or the OAuth 2.0 client creation modal. This prompts you to provide a username.

Service accounts should be created in each environment with the same username and placed in the same groups so that permissions can be promoted to higher environments.

The created service account will have its first name set to the selected username and its last name set to "Service Account". It will be automatically assigned the Service Account role.

Existing users can be converted to service accounts by placing them in the Service Accounts system group. When a service account is removed from the system group or deactivated, all API keys and OAuth 2.0 clients associated with that service account cease to work. Although they won't work, these credentials will continue to exist until they are manually deleted.

Feedback