Documentation › The REST API

Connect another application: the REST API

Your ERP, HR system or own scripts can list your published processes, start process instances with their values and follow their progress, without anybody opening SerenForce. They identify themselves with an API key of your organization.

⏱ 5 minutes📍 Menu Settings › API keys✅ Before you start: a published process

The REST API comes with the Business plan. On a lower plan, the page only shows Not included in your plan and the API refuses the calls. Only the administrators of the organization manage its API keys.

1. Create an API key

  1. Open the Settings menu, then, in the Administration section, API keys.
  2. Click New API key, give a Name that says what uses it (for instance "HR system") and choose an Expiry: Never, in 30 days, 90 days or one year.
  3. Click Create the key. The key is shown only once: copy it with Copy the key and store it in a safe place (the secret store of your other application), then click I have copied the key.

From then on, the list only shows the beginning of the key (pn_1a2b3c4d…), its state (Active, Expired, Revoked), its expiry and when it was last used. SerenForce keeps only a fingerprint of the key: if you lose it, create a new one and revoke the old one.

2. What a key can do

A key acts in this organization, in the name of the administrator who created it, with limited rights:

It completes no task (the person the task is assigned to does it), changes no process and administers nothing. It never sees another organization. It stops working when it is revoked, when it expires, or when its creator no longer administers the organization.

3. Call the API

The API keys page shows the Address of the API of your organization, like https://…/api/your-organization/public/v1, with a button to copy it. Each call sends the key in the header Authorization: Bearer your-key (or X-Api-Key: your-key). Examples with curl:

# The published processes
curl -H "Authorization: Bearer pn_your-key" https://…/api/your-organization/public/v1/processes

# Start a process instance
curl -X POST -H "Authorization: Bearer pn_your-key" -H "Content-Type: application/json" \
  -d '{"processId":"…","name":"Marie's onboarding","variables":[{"name":"Laptop","value":"MacBook"}],"participants":[{"name":"Manager","email":"paul@example.com"}]}' \
  https://…/api/your-organization/public/v1/process-instances

# Follow the process instance and its tasks
curl -H "Authorization: Bearer pn_your-key" https://…/api/your-organization/public/v1/process-instances/…/tasks

4. The answers to know

Each start made with a key appears in the audit trail in the name of its creator.

5. Revoke a key

Click Revoke next to the key, then confirm. The applications that use it are refused at once; the key stays in the list (Revoked) to keep a trace. To give them access again, create a new key.