Authenticate using OAuth 2.0 Client Credentials Flow

Machine to Machine (M2M) applications need to authenticate in order to establish authorization to use the features of the API. To learn more about the basics of authentication and authorization, read this article.

Which Method of Authentication do I Need?

This article will guide you through setting up OAuth 2.0 authentication which provides authentication without a human user, such as for scripts and other backend applications that can securely store client IDs and client secrets.

A different authentication flow is used for services which support users logging in, such as web and mobile applications. This method of authentication is not covered in this tutorial; instead, please read about Using Authorization Code Flow with PKCE.

Developer Portal Configuration

Before you start, you may need to do some initial setup in the Apiture Developer Portal.

The Apiture Developer Portal is where you can register your client application , including how it will authenticate and use Apiture APIs.

When registering this information for an application that supports Client Credentials, the Authentication type must be set as Client Credentials, and the client-id and client-secret from your Developer Portal account are required to complete the Client Credentials authentication flow.

For more information on the Developer portal and the features available, read our documentation.

OAuth 2.0 Client Credentials Authentication Code Flow

With the OAuth 2.0 authentication method, the client application requests an authentication token from the authentication server, passing application-specific information in the request header. The authentication token can then be used to confirm authentication as needed until the token expires.

Where to Authenticate

To initiate authentication, the client must know where to authenticate the user and where to obtain the API authorization access token.

OpenID Connect provides a discovery mechanism to allow a client application to get API access authorization. The client begins by fetching the OpenID Connect configuration JSON data from the target environment.

For production (live) financial institution API environment, the root OIDC authority URL is https://auth.apiture.com/oidc/ and the OIDC discovery URL is https://auth.apiture.com/oidc/.well-known/openid-configuration .

If connecting to the Customer Acceptance Test (CAT) environment, The root OIDC authority URL is https://cat-oidc.apiture-comm-preprod.com/oidc/ and the OIDC discovery URL is https://cat-oidc.apiture-comm-preprod.com/oidc/.well-known/openid-configuration .

If connecting to the second Customer Acceptance Test (CAT2) environment, The root OIDC authority URL is https://cat2-oidc.apiture-comm-preprod.com/oidc/ and the OIDC discovery URL is https://cat2-oidc.apiture-comm-preprod.com/oidc/.well-known/openid-configuration .

Use an HTTP GET on the correct OIDC discovery URL to fetch the OpenID configuration data, and save the authorization_endpoint, token_endpoint, userinfo_endpoint and other connection parameters that are used to complete the authorization flows.

Posting to the token_endpoint

Create a POST request to the token_endpoint URI, passing:

- An Authorization request header encoded credentials in the form
  Basic {encoded-credentials}
  where {encoded-credentials}
  is a Base 64 encoding of the values of your client ID and client secret for the registered client, formatted as client-id:client-secret.
  - For example, if the Client ID is c3793a03-1234-4179 and the Client Secret is 843f-6ad71454858b, concatenate them with a : as c3793a03-1234-4179:843f-6ad71454858b. Then convert this string to Base 64 to get the {encoded-credentials}.
- Pass the parameters as form data using Content-Type: application/x-www-form-urlencoded with the following data:

- - grant_type must be set to client_credentials when using client-supplied credentials.

The response is a JSON body with three properties:

Name (Type)	Description
`access_token` (`string`)	An opaque string which should be passed along with the token_type to subsequent API calls which require authentication.
`token_type` (`string`)	The form of token returned. This is typically the string `Bearer:` and the key which subsequent calls should use in the `Authorization` header when making authenticated API requests.
`expires_in` (`integer`)	The number of seconds until the `access_token` expires. Before it expires, use the `token_endpoint` to obtain a new `access_token`.

Note: There is no refresh token for client credential authentication. Instead, repeat this process before the token expires.

Passing Token Data for API Requests

The client combines token_type and access_token to form the Authorization header for API requests that require secure authorization, using this request header:

Authorization: token_type access_token

For example, if the token_type is Bearer and the acquired access_token is C1AC67D1EB404070B61DB7ECD5C635A7, the request should use

Authorization: Bearer C1AC67D1EB404070B61DB7ECD5C635A