Make your first API Calls

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

In order to issue your first successful API call you need to perform two steps

1. Obtain a valid JWT Token from our IdentityProvider.

2. Make the actual API call.

Authorization

fulfillmenttools platform is secured using an external Identity-Provider (Google Identity Platform) which issues JWT tokens in exchange for a valid username and password. This JWT token encodes (among other things) your username, your role and which facility you are assigned to in a secure way.

Authorization against our API works by using such an issued JWT Token in every request as a HTTP-Header as follows.

For the sake of simplicity we are using curl calls throughout the documentation as a "common understanding" on how a REST call should look like. Please feel free to adapt this call to your used http client technology.

Request towards Authentication Provider

curl -sSL -X POST 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=<AUTHKEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{"email": <USERNAME>,  "password": <PASSWORD>, "returnSecureToken": true}'

<AUTHKEY>, <USERNAME> and <PASSWORD> have to be valid to your fulfillmenttools instance and are being given to you when the instance was created. The user must be an email address, which is usually in the format <USER>@<YOUR_INSTANCE_NAME>.com

You can easily find your instance by looking at the Backoffice- or API-URL: Backoffice: https://<YOUR_INSTANCE_NAME>.web.app REST-API: https://<YOUR_INSTANCE_NAME>.api.fulfillmenttools.com

There is an imposed rate limit on calls towards the identitytoolkit for new tokens based on username & password (See Identity Platform - Quoatas). Currently you are able to request 25 tokens within a 10 minute period for a specific user. This could be especially relevant for connector implementations as it might be feasable to cache & share tokens between function invocations.

Response from Authentication Provider

As a result, an answer looking similar to this is responded:

{
  "kind": "identitytoolkit#VerifyPasswordResponse",
  "localId": "jdwBuqqYWdYoqWTH1Xv85EJJMpm2",
  "email": "[e-mail]",
  "displayName": "Willy Wonka",
  "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImMzZjI3NjU0MmJmZmUN0WU5OGMyMGQ2MDNlYmUyYmExMTc2ZWRhMzMiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL3NlY3VyZXRva2VuLmdvb2dsZS5jb20vb2NmZi1kZXYtYm94ZmlzaC12MS1ibHViIiwiYXVkIjoib2NmZi1kZXYtYm94ZmlzaC12MS1ibHViIiwiYXV0aF90aW1lIjoxNTkyODI0MDg2LCJ1c2VyX2lkIjoiamR3QnVxcVlXZFlvcVdUSDFYdjg1RUpKTXBtMiIsInN1YiI6Impkd0J1cXFZV2RZb3FXVEgxWHY4NUVKSk1wbTIiLCJpYXQiOjE1OTI4MjQwODYsImV4cCI6MTU5MjgyNzY4NiwiZW1haWwiOiJ0ZXN0QHRlc3QuZGUiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImZpcmViYXNlIjp7ImlkZW50aXRpZXMiOnsiZW1haWwiOlsidGVzdEB0ZXN0LmRlIl19LCJzaWduX2luX3Byb3ZpZGVyIjoicGFzc3dvcmQifX0.nTlNZTj5B3-lOToCuzEFIqTQSz4cPY1lOhdj12-RG1wOTlOoS_u5JGi4Zw4S684o07381g3ooC_B-KM2UhqaQMAkWfA_OA1cJgD_rrAdIUov_cuYdCYXHmvI-8kAajsy6R08Uh3lQYHx9tmyzbweqDFluGXEc9huH-QoWfoiwZ9Y1sjguAgC1ZCbQi3AkgKcKOqHVn8bGFxYK6KxoyXMZxaiFrfwjMQ-lov0554akQDBU0gAqLCszXtmQP7rNI5boeMIA1vo0myTXwvmYLMHIVJVn6Ej-I2SSAY1OCdafgF6k492lxJN8lJhsTsJfCynLgbiNgHJJxtBXSTSFnp2fA",
  "registered": true,
  "refreshToken": "AE0u-NeGDdHWPB0RjOYOL5AlfSO6r8CvMO6eLSXxdjMG9xiXQmBxZKJgu9OSwZ2JJc2jgSTgiNFYTFYmd1DAlfcCzpunAOF6JC8ZofkrkM75lTjMyQgxWlGWIP24dk2qaMvtAPt2oK8RtsjKx4TRQosFagokGTukQKxSWxSpTEDZl0QbWM9zmbBjzBqSK5yCWMwK2qHJpYgfJvoyAyReo76mRDC36NUpRMKoncagBq30OFCJkEgpvyI",
  "expiresIn": "3600"
}

Two attributes in the above response are of special importance:

1. idToken is the actual JWT Token you need to send along every REST Call you issue against the fulfillmenttools API. It has an expiration period to it depicted by the attribute expiresIn. In this case it is valid for 3600 seconds which equals to 1 hour. After that you need to get a fresh token.

2. refreshToken should be used to get a fresh token without providing the credentials again.

Refreshing an authorization token

In order to get a valid JWT Token after the expiration ran out you can either re-issue the call above (not recommended) or use the refreshToken given to you by the Authentication Provider (suggested):

curl -sSL -X POST 'https://securetoken.googleapis.com/v1/token' \
  -d 'grant_type=refresh_token' \
  -d 'refresh_token=<REFRESH_TOKEN>' \
  -d 'key=<AUTHKEY>'

Your first call against fulfillmenttools API

As an example please see the following request which reads the list of facilities from fulfillmenttools:

curl -sSL 'https://your.api.fulfillmenttools.com/api/facilities/' \
  --header 'Authorization: Bearer <TOKEN>'

Please take note of the HTTP Header Authorization followed by the value Bearer <AUTH_TOKEN>.

A 200 OK response would look similar to this:

{
    "facilities": [
        {
            "id": "0dee02e8-f6a7-4080-b5ab-ffa477132f35",
            "name": "Bills Candy Shop",
            "version": 3,
            "status": "ONLINE",
            "created": "2023-08-22T14:39:27.014Z",
            "lastModified": "2023-08-22T14:39:28.476Z",
            "city": "München",
            "country": "DE",
            "houseNumber": "58",
            "street": "Lilienstr.",
            "postalCode": "81669"
        }
    ],
    "total": 1
}

Congratulations!

You just made your first successful API request - nicely done! Wasn't that hard, right?

However, this is just the beginning. We suggest to proceed along our tutorials to get a better understanding about the capabilities of fulfillmenttools.

Next Steps

Now you can go ahead and rule the world with the powerful fulfillmenttools API.