Quick Start¶

Sample quickstart for Reference API

Getting started with using Reference APIs involves the following steps:

1. Create an account and a machine user.
2. Create a JSON Web Token (JWT) by using the machine user credentials.
3. Make API requests using the JWT.

Attention In the following examples we are:

1. making use of a Linux/MacOS shell in which environmental variables are set
   using the `export`-command. In other environments it may be different, e.g.
   Windows uses the `set`-command instead.

2. using the `curl` as a client. But the API can be used in any programming 
   language with an HTTP Client, e.g. Go, 
   Python, NodeJS, Javascript and Java.

Create an account and a machine user¶

The Getting Started page documents the required steps to get a hold of the clientId, clientSecret and partitionId.

Create a token¶

Use the values described in the Authorization- section to construct the Create Token request.

Example request¶

export CLIENT_ID=<YOUR_CLIENT_ID>
export CLIENT_SECRET=<YOUR_CLIENT_SECRET>

curl {{env.issUrl}} \
  -H 'content-type: application/json' \
  -d "{
            \"client_id\":\"$CLIENT_ID\",
            \"client_secret\":\"$CLIENT_SECRET\",
            \"audience\":\"{{env.audience}}\",
            \"grant_type\":\"client_credentials\"
      }"

To run this example yourself, set the CLIENT_ID and CLIENT_SECRET first.

Example response¶

{
  "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt",
  "token_type": "Bearer",
  "expires_in": 86400
}

The token, or JWT (JSON Web Token), is the value of the access_token-property in the response. You can now use it by passing it in the Authorization-header of any subsequent API requests. The expires_in-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token.

Now you have all you need to start using the API. As a last step of preparation set the token and partitionId as environmental variables.

export PARTITION=<YOUR_PARTITION_ID>
export TOKEN=<YOUR_TOKEN>

Make API requests¶

This guide will take you through the steps you need to perform to call and use the Security Workflow API.

Workflows¶

Before you can create a workflow instance, you need to get the Id of the respective workflow. You can do so, by executing the following request:

curl
  -H "Authorization: Bearer $TOKEN" 
  "{{buildingxopenness.env.selfServiceApiUrl}}/partitions/$PARTITION/api/v1/workflows?showInSsp=true"

Example Response¶

[
  {
    "id": "dd52c89a-e5b3-49fe-9f7c-6c72ee5ac0d8", // you will need this in the next step
    "name": "Your Workflow",
    "description": "Your Workflow's description",
    "active": true
  }
]

You might see a translation key as a name and description, depending on the configuration. Please keep in mind you will need to include the query parameter. If you don't, you will likely receive a 403 Forbidden.

Workflow Instances¶

Once you have obtained the Id of the workflow you want to start, find out which payload the workflow requires, which is dependant on the process' definition. Set them as the environmental variable PAYLOAD (as shown in the curl). They have to be a JSON-object, which can contain any content.

Then, do the following request:

curl 
  -X POST
  -H "Authorization: Bearer $TOKEN"
  -H "Content-Type: application/json"
  -d '{ "workflowId": "dd52c89a-e5b3-49fe-9f7c-6c72ee5ac0d8", "instanceVariables": $PAYLOAD }'
  "{{buildingxopenness.env.selfServiceApiUrl}}/partitions/$PARTITION/api/v1/workflow-instances"

This will return a 204 No Content if everything went as expected. Keep in mind that errors in the workflow itself will not be visible at this point. If there's a mistake with the content of the instanceVariables you will not be informed by the API.