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 tutorial 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 credentials.

OpenID Connect authentication is meant for services which support users, such as web and mobile applications. This method of authentication is not covered in this tutorial; instead, please read about using OpenID Connect.

Developer Portal Configuration

The authenticated portion of the Developer Portal must be used to register your application. For more information on creating an application in the Developer portal, read this article Creating Applications. You may also explore more of the Authenticated Portal section for additional information on the Developer Portal.

The application’s Authentication type must be set as Client Credentials, and the client-id, client-secret from your Dev Portal account and the scope of the application are required to complete the Client Credentials authentication flow.

Listing Application Scopes

Every application in the Developer Portal has selected scopes that grants permission for the application to read or write specific information. This scope must be passed when requesting an access token for client credentials.

The scopes needed for functions are listed in the API Documentation. Under each functions description is a blue callout that lists the scopes required.

Every scope required by the functions the application uses must be listed in the initial request for a client credential token. Below is an example formatting of the scopes for reading and for writing using the banking API that is included in the token POST request. Each separate scope is separated by a space.

&scope=banking/read banking/write

OAuth 2.0 Client Credentials Authentication Code Flow

With this authentication method, the client requests an authentication token from the authentication server, passing application-specific information in the request header. The token can then be used to make API calls until it expires.

Getting the token_endpoint

The client must know where to obtain the access token. The client begins by fetching the OpenID Connect configuration JSON data (which is also used for OAuth 2.0 authentication).

Use an HTTP GET at https://auth.apiture.com/oidc/.well-known/openid-configuration to fetch the configuration data. Save the token_endpointthat is used to complete the authorization flow.

Posting to the token_endpoint

POST to the token_endpoint URI from the configuration data, passing:

- An Authorization request header encoded credentials in the form
  Basic {encoded-credentials}
  where {encoded-credentials} is a Base 64 encoding of the text client-id:client-secret for the registered client.
- Pass the parameters as form data using Content-Type: application/x-www-form-urlencoded.

- - This data required is the client-id, client-secret, scope, and grant_type
  - client-id, client-secret, and scope have been discussed elsewhere in this article.
  - grant_type must be set to client_credentials when using client-supplied credentials.
  - Example Formatting Template:
  - ```
  client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}&scope={SCOPES}&grant_type=client_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