Web API Authentication (2024)

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 four ways to authenticate when calling a web API:

1. API key authentication
2. Basic authentication
3. OAuth 2.0 Client Credentials Grant
4. 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

Note:If you encounter a 404 error while using an API key, make sure that the corresponding service account has been added to a group that has permission to call the web API.

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.

Tip:OAuth 2.0 clients can use the same service accounts as API keys. This makes it very easy to update a call using API keys to use the OAuth 2.0 Client Credentials grant instead. If you use the same service account, you won't even need to update object security.

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.

Note:If you encounter a 404 error while using the Client Credentials grant, make sure that the corresponding service account has been added to a group that has permission to call the web API.

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.

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.