Uh oh!
There was an error while loading. Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork 249
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 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:
$ export TOKEN="your generated token"
$ curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" https://example.processmaker.net/api/1.0/requests$token = 'your generated token';
$client = newGuzzleHttp\Client(['base_uri' => 'https://example.processmaker.net/api/1.0/']);
$headers = [
'Authorization' => 'Bearer ' . $token,
'Accept' => 'application/json'
];
$response = $client->request('GET', 'requests', [
'headers' => $headers
]);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.
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.
- 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
- 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
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.
- 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 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.
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.
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
- 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