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.
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
- Open the Settings menu, then, in the Administration section, API keys.
- 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.
- 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:
- list the published processes and see what a start can fill in (variables that can change, participants);
- start a process instance;
- follow the process instances it started and their tasks (state, values of the variables, dates).
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
- Only the variables the process lets a start change take a value; for a list, give the names of the options separated by commas.
- A participant is played by the person whose email you give; otherwise by their default person. Personas are played by whoever holds them.
- The OpenAPI document link of the page opens the full description of the API (OpenAPI format, which tools such as Postman or Swagger import).
4. The answers to know
- 401: the key is missing, unknown, revoked or expired.
- 402: the plan of the organization does not include the REST API, or the subscription ended.
- 403: the creator of the key does not have the permission (for instance to start process instances).
- 400: a value does not fit the process; the message says which.
- 429: more than 120 calls a minute with the same key; wait the number of seconds given by the
Retry-Afterheader before trying again.
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.