Web API Authentication

Introduction

This article 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.

There are three ways to authenticate users when calling a web API:

  1. API key authentication
  2. Basic authentication
  3. Session-based authentication

If you wish to invoke an Appian Web API from another system, you must use either API key or basic authentication.

API Key Authentication

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

  • 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 have access to that web API.

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.

Session-Based Authentication

Session-based authentication is reserved for browser-initiated web API calls. A session can be established using either the standard Appian login 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