Authentication

Getting a token

Before accessing the API, you will need a personal API key from i-Fulfilment. This key is used to identify yourself to the API and receive an access token, required to access any of the API endpoints. These tokens are temporary and will auto expire after 30 minutes of no use.

To generate an authentication token, perform an authentication request, sending your personal and private keys. The API will generate an authentication token which is valid for one hour.

You must send this token in the header of any subsequent requests.

There is no limit to the number of authentication requests you make – you can perform one authentication request, store the token and use it until it expires, or perform a separate authentication request to generate a new token before each separate API call.

Each API request you make will contain a meta section in the response, which contains information on when your security token is due to expire.

<?php

// For this example we are using the popular library Guzzle.
// Details on how to install and use Guzzle can be found at:
// http://docs.guzzlephp.org/en/latest/

// Load up Guzzle to perform the http request
$client = new GuzzleHttp\Client();

// Request an access token
$tokenRequest = $client->request('POST', 'https://public-api.bladepro.io/v1/auth/login', [
    'body' => json_encode([
        'username' => 'geminize-direct',
        'password' => 'API_SECRET_KEY'
    ]),
]);

// Get the access token
$auth = json_decode($tokenRequest->getBody(), true);

// Did we receive a token?
if(empty($auth["data"]["token"])) {
    throw new \Exception("Failed to get an access token");
}

require 'rest-client'
require 'json'

# Request an access token
auth = RestClient.post 'https://public-api.bladepro.io/v1/auth/login', {
    'username' => 'geminize-direct',
    'password' => 'API_SECRET_KEY'
}.to_json, {
    content_type: :json,
    accept: :json
}

auth = JSON.parse(auth)

# Did we receive a token?
if ( !auth['data']['token'] )
    raise RuntimeError, "Failed to get an access token"
end

// Require the node HTTP module
var request = require('request');

// Request an access token
request({method: 'POST', json:true, uri: 'https://public-api.bladepro.io/v1/auth/login', body: {username: 'geminize-direct', password: 'API_SECRET_KEY'}}, function (error, response, body) {

    // Get the access token
    var auth = body;

    // Did we receive a token?
    if ( !auth || !auth.data || !auth.data.token ) {
        throw "Failed to get an access token";
    }
});

# Request an access token
curl -XPOST -H "Content-type: application/json" -d '{"username":"geminize-direct","password":"API_SECRET_KEY"}' 'https://public-api.bladepro.io/v1/auth/login'

Make sure to replace API_SECRET_KEY with your API key. The endpoint returns a JSON user object, structured like this:

{
    "meta": {
        "request_reference": "1vd88ym25-c893v8t"
    },
    "data": {
        "session_token": "9nYQgN1Z7M8Fj15CjXDm1DAC4SIPItcD5I0enaZ5bVLHUKvn6sGfstYadhSpnBGurEBZ3L4es9ZWIrlFBviBBBxXrah1FcnHS43Q",
        "expiry": "2020-01-15T17:09:15.000Z"
    }
}

Rate limiting

Every authenticated API call deducts credits from your request bucket. The number of credits deducted depends on the endpoint — cheap lookups cost 1, bulk operations cost more. The cost for each endpoint is listed in the endpoint’s documentation and exposed in the OpenAPI spec as x-rate-limit-cost.

Every response includes the current state of your bucket in the meta object, as shown in the example.

Every authenticated response also includes the following headers:

Header	Description
`X-RateLimit-Limit`	Your total bucket capacity
`X-RateLimit-Remaining`	Credits remaining after this call
`X-RateLimit-Cost`	Credits deducted by this call

When your bucket is exhausted, the API returns HTTP 429 instead of processing the request. The response includes a Retry-After header indicating how many seconds to wait before your bucket has refilled enough to afford the next call.

{
  "meta": {
    "request_rate_limit": {
      "requests_remaining": 5000,
      "cost": 1
    }
  }
}

POST /v1/auth/login

Log into BladePRO.

Request Body

Login

Return Type

Auth

Types for the Request Body

Key	Description	Types	Restrictions
`username`	The username.	`string`	`required` not `null` `min length` is `2`
`password`	The password.	`string`	`required` not `null` `min length` is `3`

Rate limit cost

Each call to this endpoint deducts 1 credit from your request bucket.

Scopes

This endpoint is available to all users.

<?php

// Instantiate a GuzzleHttp client
$client = new \GuzzleHttp\Client();

// Make the request
$response = $client->request("POST", "https://public-api.bladepro.io/v1/auth/login", [
    "body" => json_encode([
        "username" => "my-login",
        "password" => "my-password",
    ]),
    "headers" => [
        "Content-Type" => "application/json",
    ],
]);

// Process the response
$responseBody = json_decode($response->getBody(), true);

require 'rest-client'
require 'json'

# Make the request
response = RestClient.post 'https://public-api.bladepro.io/v1/auth/login', {
  username: "my-login",
  password: "my-password",
}, {
  content_type: :json,
  accept: :json
}

# Process the response
puts response.body

// Require the node HTTP module
var request = require("request");

// Make the request
request({
    method: "POST",
    json: true,
    uri: "https://public-api.bladepro.io/v1/auth/login",
    body: {
        "username": "my-login",
        "password": "my-password"
    },
    headers: {
        "Content-Type": "application/json",
    },
    (error, response, body) => {
        // Process the response
        console.log(body);
    },
});

# Make the request
curl --location --request POST 'https://public-api.bladepro.io/v1/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "my-login",
    "password": "my-password"
}'

Example result:

{
    "meta": {
        "request_reference": "235chjz9h-c893v86"
    },
    "data": {
        "session_token": "Ydf8R566FT2AF51DStGEQitsmasrwSxvXVHju8N0U4B66pxRY2l1Dz5F7ikfr2gaqDl8AGGciXECh8Uf5jMfxJpFaixM4qKgXtP3",
        "expiry": "2026-10-27T07:38:35.000Z"
    }
}

Revoke Token

DELETE /v1/auth/revoke-token

Revoke session token.

Return Type

Empty.

Rate limit cost

Each call to this endpoint deducts 1 credit from your request bucket.

Scopes

This endpoint is available to all users.

<?php

// Instantiate a GuzzleHttp client
$client = new \GuzzleHttp\Client();

// Make the request
$response = $client->request("DELETE", "https://public-api.bladepro.io/v1/auth/revoke-token", [
    "headers" => [
        "Content-Type" => "application/json",
        "Access-Token" => "my-token-from-login",
    ],
]);

// Process the response
$responseBody = json_decode($response->getBody(), true);

require 'rest-client'
require 'json'

# Make the request
response = RestClient.delete 'https://public-api.bladepro.io/v1/auth/revoke-token', {
  access_token: 'my-token-from-login',
  content_type: :json,
  accept: :json
}

# Process the response
puts response.body

// Require the node HTTP module
var request = require("request");

// Make the request
request({
    method: "DELETE",
    json: true,
    uri: "https://public-api.bladepro.io/v1/auth/revoke-token",
    headers: {
        "Access-Token": "my-token-from-login",
        "Content-Type": "application/json",
    },
    (error, response, body) => {
        // Process the response
        console.log(body);
    },
});

# Make the request
curl --location --request DELETE 'https://public-api.bladepro.io/v1/auth/revoke-token' \
--header 'Content-Type: application/json' \
--header 'Access-Token: my-token-from-login'

Example result:

null

Authentication

Getting a token

Rate limiting

Login

Request Body

Return Type

Types for the Request Body

Login (root level)

Rate limit cost

Scopes

Revoke Token

Return Type

Rate limit cost

Scopes