Skip to content

API Authentication

Jump to bottom
tdondich edited this page Jul 8, 2019 · 4 revisions

ProcessMaker API Authentication

ProcessMaker utilizes OAuth for API Authentication and allows multiple OAuth grant types for use in external user applications as well as service to service communication. Users can have their own tokens created for direct API authentication or authentication clients can be created by the Administrator to represent external applications to authenticate for client based authentication.

Personal API Access Tokens

Personal API Access Tokens are the easiest way to get started with the API and are used to communicate to the API as the user they were generated for. Personal API Access Tokens can be generated by Administrators when manging Users in the system. Once a user is created, the administrator can navigate to the user in Administration and visit the API Tokens tab. Click the Generate New Token button to generate a token which will represent the user. This token can then be utilized for the bearer token when calling the API directly. This bypasses any auth handshake and should not be utilized unless a grant type handshake below is not appropriate.

Once the token is generated, it can be used as a Bearer token in your API calls. As an example:

CURL Example

$ export TOKEN="your generated token"
$ curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" https://example.processmaker.net/api/1.0/requests

PHP Example

$token = 'your generated token';
$client = new GuzzleHttp\Client(['base_uri' => 'https://example.processmaker.net/api/1.0/']);
$headers = [
  'Authorization' => 'Bearer ' . $token,
  'Accept'        => 'application/json'
];
$response = $client->request('GET', 'requests', [
  'headers' => $headers
]);

Generating Authentication Clients

For client, password and authorization grant types, a application authentication client must be setup in ProcessMaker. Navigate to Auth Clients in Administration to manage the collection of clients. To add a client, provide a unique name as well as the redirect url ProcessMaker should return to when returning an authorization code. When you've created the client, you'll have the Client ID as well as the client secret. These are used to identify the client when using grant types that utilize a client.

Client Credentials Grant

The client credentials grant is utilized for service to service communication. This is used for API calls where user authentication or permission is not necessary. Only special routes in the API are allowed to be accessed by this method.

The following steps are used when using the client credentials grant.

  1. The client sends a POST request to /oauth/token with the following parameters grant_type: client_credentials client_id: The numeric ID of the client (Example: 42) client_secret: The secret of the client, found in the client list in Auth Clients scope: Optional, provide scope to use for the access token used
  2. ProcessMaker will respond to the request with a JSON object that contains the following properties: token_type: Bearer expires_in: An integer representing the TTL of the access token access_token: The access token to use as the Bearer token in future API requests

Authorization Code Grant

The authorization code grant type is normally used in interactive user applications. The external application would redirect the user to a ProcessMaker login and grant screen. The user will require logging into ProcessMaker and then authorize access to the external application. The system then provides an access token which can then be used for future API requests and act as that user.

Clone this wiki locally