API authentication

AppDirect REST and GraphQL APIs use an OAuth-authenticated interface that facilitates secure data access by partners and developers. We recommend that you use OAuth 2.0 whenever possible, because OAuth 1.0 was deprecated on 1 December 2020. When authenticated, API users can read, create, edit, or delete marketplace data.

All API requests must be made over HTTPS. Any calls made over HTTP will fail. API requests without authentication will also fail.

Any authenticated API call requires an API client so that AppDirect and your product can exchange keys and secrets. Marketplace Managers can create API clients. For more information, see API clients.

Store API keys as securely as possible to protect your data. After they are generated, do not share your API keys in publicly accessible areas such as client-side code or code-sharing platforms.

OAuth 2.0 authentication

OAuth 2.0 authentication uses access tokens to determine which APIs a client can successfully call. Access tokens are opaque strings, generated by AppDirect, that represent an API client's permissions. Access tokens must be included in every API request that you make. The process of obtaining and using access tokens follows a generic pattern, with variations depending on the needs of your application and API client configuration:

1. The client requests an access token from AppDirect.
2. AppDirect authenticates the client and user (if one exists), then returns an access token to the client.
3. The client makes API requests to AppDirect using the access token.

OAuth 2.0 client authentication uses two main building blocks: grant types and scopes.

Scopes define the permissions that the client requests from AppDirect. The access token that AppDirect returns includes the requested scopes, which in turn determine which API calls the client can make on behalf of the user. In the context of AppDirect, scopes often correspond to AppDirect user roles.

Grant types define the type of access the client requires (user-level or system-level), and determine how the client obtains the access token (for example, by using a user password, authorization code, and so on). AppDirect supports several grant types, each of which serves a different purpose. Different APIs support different grant types.

When you integrate with AppDirect, ensure that you use the appropriate scopes and grant types for your use cases.

The following sections describe scopes and grant types in more detail:

• Grant types
• Scopes

To create and edit API clients, see API clients.