API Authentication

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.

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

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.

The following steps are used when using the authorization code grant.

The client sends a GET request to /oauth/authorization with the following parameters

• client_id: The numeric ID of the client (Example: 42)
• response_type: code
• scope: Optional, provide scope to use for the access token used

ProcessMaker authenticates the user and asks for permission

ProcessMaker will check to see if the user is currently logged in. If not, they will be asked to login. Once logged in, they'll be prompted to authorize the external application to access their account. The user most authorize this access in order for the process to continue.

ProcessMaker redirects the user to the redirect url configured for the client

If the user denied access in the previous screen, a url parameter called error will be set with the message access_denied.

If the user approved access, a url parameter called code will be set with the authorization code to exchange for an access token in the next step.

Client exchanges the authorizaton code for an api access token

The client sends a POST request to /oauth/token with the following parameters

• grant_type: authorization_code
• 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
• redirect_uri: The redirect url of the client. This MUST match the redirect url specified in the client configuration
• response_type: code
• scope: Optional, provide scope to use for the access token used

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
• refresh_token: The refresh token which can be used to obtain a new access token if the current access token expires