The capabilities described on this page are included in Appian's standard capability tier. Usage limits may apply. |
This page explains how to call an Appian web API object.
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:
If you wish to invoke an Appian Web API from another system, you cannot use session-based authentication.
API keys can be used to authenticate Appian Web APIs. There are several advantages to using API keys over basic authentication:
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.
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.
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.
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.
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.
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 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.
Web API Authentication