Web API Authentication

Overview

This page explains how to call an Appian web API object.

• To learn about web APIs and their configuration options, see Web APIs.
• To learn the basic steps involved with creating an API, see Creating Web APIs.
• For a real-world example of how to build and test web APIs in Appian, see the Web API Tutorial.

Authentication

Web APIs can only be called by an authenticated Appian user or service account.

There are five ways to authenticate when calling a web API:

1. API key authentication
2. Basic authentication
3. OAuth 2.0 Client Credentials Grant
4. Mutual TLS authentication
5. Session-based authentication

If you wish to invoke an Appian Web API from another system, you cannot use session-based authentication.

API key authentication

API keys can be used to authenticate Appian Web APIs. There are several advantages to using API keys over basic authentication:

• Security: API keys are randomly generated and can't be used to log into Appian.
• Performance: API keys work up to 10x faster than using username/password.
• Longevity: API keys don't expire automatically, so you won't need to keep rotating credentials in systems that call Appian web APIs.

Service Accounts

Each API key is tied to a service account. To invoke a web API with an API key, the associated service account must be granted access to that web API via group management.

API keys and service accounts can be managed in the Admin Console by system administrators. 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. API keys can only be used for the environment they're created in.

Using API Keys

Once object security has been configured for a service account, there are multiple ways to use API keys:

• appian-api-key Header:
  curl https://example.appian.com/suite/webapi/endpoint -H "appian-api-key: ${API_KEY}"

• Bearer Token Header:
  curl https://example.appian.com/suite/webapi/endpoint -H "Authorization: Bearer ${API_KEY}"

• Basic Authentication Header (with null username):
  curl -u :${API_KEY} https://example.appian.com/suite/webapi/endpoint

• Basic Authentication Header (with null password):
  curl -u ${API_KEY}: https://example.appian.com/suite/webapi/endpoint

Basic authentication

Users that use Appian authentication or LDAP authentication can use their Appian username and password to call web APIs:

curl -u ${USERNAME}:${PASSWORD} https://example.appian.com/suite/webapi/endpoint

Basic authentication cannot be used by members of the SAML system group or Service Accounts system group.

OAuth 2.0 Client Credentials grant

The OAuth 2.0 Client Credentials grant can also be used to invoke web APIs.

OAuth 2.0 is the industry-standard protocol for authorization, and should generally be used when possible.

Service accounts

Like API keys, each OAuth 2.0 client is tied to a service account. To invoke a web API with an OAuth 2.0 client using the Client Credentials grant, the associated service account must be granted access to that web API via group management.

OAuth 2.0 clients and service accounts can be managed in the Admin Console by system administrators. 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. OAuth 2.0 clients can only be used for the environment they're created in.

Using the OAuth 2.0 Client Credentials grant

One option for using the Client Credentials grant to authenticate web APIs is to use an Appian OAuth 2.0 client. We implemented the OAuth 2.0 Client Credentials grant as defined by the IETF RFC 6749 standard. For our implementation, the scope parameter must either be blank or omitted entirely.

Another option for using the Client Credentials grant to authenticate web APIs is to use a third-party OAuth 2.0 client. The third-party OAuth provider must provide an access code in the JWT format to work with Appian.

To learn how to use an Appian connected system to invoke a web API with the Client Credentials Grant, see OAuth 2.0: Client Credentials Grant.

Mutual TLS authentication

Mutual TLS (mTLS) authentication verifies the identity of both the client and server before a web API request is fulfilled. Your organization may want to use this stricter authentication when web APIs provide access to sensitive data.

This authentication option must be configured by an administrator by uploading the client certificates that the environment should trust. Then, web API requests using these client certificates will be recognized and authenticated by Appian.

When mutual TLS is enabled, it applies to all web APIs and all applications in an environment. Web API requests from portals will not work if mTLS is enabled.

Construct a web API request for mutual TLS authentication

When mTLS is enabled, client requests that invoke a web API must meet the following requirements.

1. Configure your HTTP client to use the client certificate and the client certificate chain when connecting to your web API.
2. The combined size of all request headers and the client certificate cannot exceed 8 KB.
3. The request must still include the required credentials for the API request (OAuth 2.0, API key, or basic).
4. The request URL must specify port 8443. For example, the request URL to get customer data may look something like https://example.appiancloud.com:8443/suite/webapi/customers.

Session-based authentication

Session-based authentication is reserved for browser-initiated web API calls. A session can be established using either the standard Appian sign-on page or via a SAML SSO configuration. When a user invokes an Appian web API from their browser (for instance to populate a task list for use with an embedded interface), session cookies will be honored.

Feedback