# Access to fulfillmenttools APIs
There are multiple methods to make API calls with fulfillmenttools. In this article, we'll take you through making your first API calls with Postman, cURL, and GraphQL.
{% hint style="info" %}
If you're on a free trial, we suggest following our [free trial guides](https://docs.fulfillmenttools.com/documentation/using-our-free-trial/free-trial-information).
{% endhint %}
{% hint style="success" %}
## Prerequisites
* fulfillmenttools tenant[^1] and login credentials
{% endhint %}
If you don't have access to a tenant[^1], you'll need to ask the Administrator in your team to invite you. Once invited, you'll have access to the information below that you'll need to work with our APIs:
* API URL of your tenant[^1]
* API key (also referred to as `AUTHKEY`)
* Username
* Password
## Postman
A comprehensive [Postman](https://www.postman.com/) collection is used and frequently updated with new requests as they appear in the API. To work with the collection, follow the steps below:
{% stepper %}
{% step %}
**Import the fulfillmenttools collection to Postman**
Download the [raw GitHub file](https://raw.githubusercontent.com/fulfillmenttools/fulfillmenttools-api-reference/master/fulfillmenttoolsAPI.postman_collection.json) and add it to the collection section of Postman.
{% hint style="info" %}
This collection are regularly updated. It's recommended to periodically update the local collection to get the latest changes.
{% endhint %}
{% endstep %}
{% step %}
**Create an environment**
Go to the environment section and create a new environment. Add the below to your new environment. Your `projectId` is your tenant name and can be found in the email you received from us, which will resemble `ocff-{uniqueID}-pre`.
| Variable | Value |
|---|
projectId | {the project ID in the email you received} |
host | https://{projectId}.api.fulfillmenttools.com/ |
{% endstep %}
{% step %}
**Add credentials to the Postman Vault**
Go to the Postman Vault (bottom right of the Postman screen), and add the below to your Vault. You'll find all the values in the email you received from us (if you've changed the password in Backoffice, use that password instead of the one in the email).
| Variable | Value |
| ---------------------- | ---------------------------------------- |
| `{projectId}-user` | {the username in the email you received} |
| `{projectId}-password` | {the password in the email you received} |
| `{projectId}-api-key` | {the API key in the email you received} |
{% hint style="info" %}
We use the Postman Vault to store these sensitive variables to avoid syncing them to the Postman Cloud.
{% endhint %}
{% endstep %}
{% step %}
**Make your first API call to get an Auth token**
Go to the fulfillmenttools collection, select `POST Request Auth Token`, ensure your environment is selected, and click **Send**.
You should get a `200` response. If you go back to your environment settings, you'll see that an `authToken` and a `refreshToken` have been automatically created.
{% hint style="info" %}
You'll need to run the `POST Refresh Auth Token` endpoint at least every 60 minutes.
{% endhint %}
{% endstep %}
{% endstepper %}
You're now ready to use all the other calls in the Postman collection. :tada:
For example:
```http
GET https://{projectId}.api.fulfillmenttools.com/api/facilities
```
## cURL
cURL is one command line tool (CLI) you can use to do REST API calls. Here's an example of how it must be used for our platform.
{% stepper %}
{% step %}
**Get an authentication token**
Open your preferred CLI and use the below input.
You'll need to add your own `AUTHKEY`, `email`, and `password`.
curl -sSL -X POST 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={authKey}' \
--header 'content-Type: application/json' \
--data-raw '{
"email": "{your-email-address}",
"password": "{your-password}",
"returnSecureToken": true
}'
Be sure to make note of both the `idToken` and `refreshToken` as you'll need both of these.
{% endstep %}
{% step %}
**Make an API call**
You're now ready to use all the other API calls using cURL. For example, the below will create a new facility. You'll need to replace `{projectID}` with your tenant name, and replace `{idToken}` with the authorization token from above.
{% hint style="info" %}
You must send headers for `Authorization` and `Content-Type`. Also replace `https://{projectId}.api.fulfillmenttools.com/api/facilities` with your specific host and endpoint.
{% endhint %}
curl -sSL -X POST 'https://{projectId}.api.fulfillmenttools.com/api/facilities' \
--header 'Authorization: Bearer {idToken}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Nerd Herd Clothing",
"address": {
"companyName": "Nerd Herd Clothing",
"country": "US",
"postalCode": "81669",
"city": "München",
"street": "Lilienstr.",
"houseNumber": "58"
},
"services": [
{
"type": "COLLECT"
}
],
"status": "ONLINE",
"locationType": "STORE"
}'
{% endstep %}
{% endstepper %}
{% hint style="info" %}
You'll need to call the `POST Refresh Auth Token` endpoint at least every 60 minutes.
{% endhint %}
## GraphQL Explorer
### fulfillmenttools GraphiQL
The official fulfillmenttools playground, powered by GraphiQL, is hosted under `https://{projectId}.graphql.fulfillmenttools.com/graphql`. It enables interactive exploration of queries and documentation. Authentication tokens must be entered in the **Headers** tab at the bottom of the page.
### Altair
For in-depth query development on the fulfillmenttools GraphQL API, we recommend [Altair](https://altairgraphql.dev/), available as a browser plugin and a standalone application. We also provide a pre-request script to automatically refresh authentication tokens, similar to our Postman collection.
To start with Altair, enter your tenant's GraphQL URL in the URL bar. Note that using Altair for schema introspection won't include schema directives and lifecycle information from generated GraphQL schemas.
#### Pre-request script for Altair
The following guide shows how to set up a pre-request script in Altair.
{% stepper %}
{% step %}
**Create a new environment**
First, create a new environment for your tenant:
Fill the following information in the environment:
```json
{
"user": "YOUR-USER-EMAIL",
"password": "YOUR-PASSWORD",
"host": "https://{projectId}.graphql.fulfillmenttools.com/graphql",
"apiKey": "YOUR-API-KEY"
}
```
{% endstep %}
{% step %}
**Add the Pre-request script**
Click on the **Pre-request** tab and add the script below. Ensure you've checked the Enable pre-request script check box.
{% code title="Pre-request script to copy" %}
```javascript
const lastTokenCall = await altair.storage.get("lastTokenCall");
const now = new Date();
if (!lastTokenCall || now - (new Date(lastTokenCall)) > 1800000) {
altair.log("Refreshing token...");
var user = altair.helpers.getEnvironment('user');
var apiKey = altair.helpers.getEnvironment("apiKey");
var escapedPwd = altair.helpers.getEnvironment('password');
escapedPwd = escapedPwd.replace(/\\/g, '\\\\');
escapedPwd = escapedPwd.replace(/\'/g, '\\\'');
escapedPwd = escapedPwd.replace(/\"/g, '\\\"');
escapedPwd = escapedPwd.replace(/\`/g, '\\\`');
await altair.storage.set("lastTokenCall", new Date());
const authUrl = 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=' + apiKey
const authResult = await fetch(authUrl, {
"method": "POST",
"body": JSON.stringify({
"email": user,
"password": escapedPwd,
"returnSecureToken": true
})
}).catch((e) => altair.log(e))
const data = await authResult.json()
altair.helpers.setEnvironment("authToken", data.idToken, true);
altair.helpers.setEnvironment("refreshToken", data.refreshToken, true);
}
```
{% endcode %}
{% endstep %}
{% step %}
**Adjust the Authentication header**
Click the **Set Headers** icon in the left-hand navigation.
Then, adjust the authentication header to use the automatically generated token and click **Done**.
The script will automatically refresh the authentication token when it's older than 30 minutes.
{% endstep %}
{% endstepper %}
[^1]: An instance of fulfillmenttools for each customer. Each tenant works in different environments. For example, there'll be a tenant for pre-production, and one for production.