Skip to content

API

Introduction

apifew core task is to grant/check end-users licenses, and when applicable, register usage.

Standalone applications and SaaS can request apifew to check if a given user has been assigned a license. It is done by requesting apifew's API.

APIs applications can also check user rights to request and register requests usage, with 3 different methods.

To interact with apifew's API as a provider, your calls need to be authenticated.
Apifew-Key is available on apifew's website, in Provider mode, on Applications General settings 

headers:
  {
    "Content-Type":             "application/json",
    "Apifew-Key":               "12345678-aaaa-bbbb-cccc-1234567890abcdef"
  }

Info

Currently /v2/ is currently in production.
/v1/ is still available for backward compatibility.

Users management

apifew's API enable your application back-end to manage your end-users directly.
The basic usage includes checking your users'permissions: license status and features.
More advances usages cover end-users login, password management...

User creation

Creates a new user for provider's application and apifew platform.
POST https://gw.apifew.com/v2/app/user/create 

  {
    "USER_LOGIN":               "user.name@example.com"
  }

Response (Result object) 

Result.data:
  {
    "uid":                      "ABCDEF1234567890",
  }
Result.success_msg:             "INFO_APP_USER_CREATED"
Result.error_msg:               "ERROR_USER_NOT_FOUND"

User information

Retrieve information about the user and the license that has been assigned to them.

POST https://gw.apifew.com/v2/app/user 

  {
    "USER_LOGIN": "user.name@example.com"
    }

Response (Result object) 

Result.data: 
  {
    "login":                    "user.name@example.com",
    "uid":                      "ABCDEF1234567890",
    "app":                      "app.domain.com",
    "license_key":              "12345678-aaaa-bbbb-cccc-1234567890abcdef",
    "pricing_fullname":         "monthly_10 rev.21",
    "license_role":             "normal_user",
    "license_features":         ["read_report", "download_report"],
    "license_active":           true,
    "license_status":           "subscribed"
  }
Result.error_msg:               "ERROR_USER_NOT_FOUND"

User deletion

Delete an end-user for your application (only).
apifew's related user will not be deleted (they keep access to their invoices, and eventually other applications)

POST https://gw.apifew.com/v2/app/user/delete 

  {
    "USER_LOGIN":               "user.name@example.com"
  }

Response (Result object) 

Result.success_msg:             "INFO_APP_USER_DELETED"
Result.error_msg:               "ERROR_MISSIN_PARAMETER"
                                "ERROR_USER_NOT_FOUND"

Managed user creation

Add a managed user to an owner's team
A managed user is an end-user controled by a licenses owner. It allows any license owner to assign and revoke licenses to its managed users, without the need for them to interact with apifew.

POST https://gw.apifew.com/v2/user/managed/create 

  {
    "OWNER_LOGIN":              "user1.name1@example.com"
    "MANAGED_LOGIN":            "user2.name2@example.com"
  }

Response (Result object) 

Result.success_msg:             "INFO_MANAGED_USER_CREATED_Params || <LOGIN>"
Result.error_msg:               "ERROR_MISSIN_PARAMETER"
                                "ERROR_USER_NOT_FOUND"

Managed user removal

Remove a managed user from an owner's team, if no license assigned to managed user.

POST https://gw.apifew.com/v2/user/managed/remove 

  {
    "OWNER_LOGIN":              "user1.name1@example.com"
    "MANAGED_LOGIN":            "user2.name2@example.com"
  }

Response (Result object) 

Result.success_msg:             "INFO_MANAGED_USER_REMOVED"
Result.error_msg:               "ERROR_USER_NOT_FOUND"

User login

  {

  }

Pricings & Licenses

Pricings

Retrieves basic information for all pricings (if CURRENT_REV_ONLY is missing or set to 0, returns lastest revision + all revisions with at least one license attached, otherwise returns only lastest revision).
POST https://gw.apifew.com/v2/app/pricings 

  {
    "CURRENT_REV_ONLY"?         1
  }

Response (Result object) 

Result.data: 
  {
    "pricings": [
      {
        "pricing_name":         "Monthly pricing",
        "pricing_rev":          10,
        "licenses_count":       133,
        "features":             [<feature>, ...]
      } 
      ...
    ]
  }

Pricings and licenses details

Retrieve information for all pricings (lastest revision + all revisions with at least one license attached) and licenses information.
POST https://gw.apifew.com/v2/app/pricings 

  {
  }

Response (Result object) 

Result.data: 
  {
    "pricings": [
      {
        "pricing_name":         "Monthly pricing",
        "pricing_rev":          10,
        "licenses": [
          {
            "key":             "",
            "pricing_fullname": "Monthly pricing rev.10",
            "period_freq":      "monthly",
            "end_dt":           "2022-02-28",
            "active":           "true",
            "status":           "subscribed",
            "owner_login":      "john.smith@noname.com",
            "user_login":       "agent_smith@noname.com"
          }
          ...
        ]
      } 
      ...
    ]
  }

License information

License information is available on /v2/app/user (see User information)
But you can directly get information with license key:

POST https://gw.apifew.com/v2/app/license 

  {
    "USER_LICENSE":             "12345678-aaaa-bbbb-cccc-1234567890abcdef"
  }

Result.data: 
  {
    "login":                    "user.name@example.com",
    "uid":                      "ABCDEF1234567890",
    "app":                      "app.domain.com",
    "license_number":           "12345678-aaaa-bbbb-cccc-1234567890abcdef",
    "pricing_name":             "monthly_10 rev.21",
    "pricing_features":         [],
    "pricing_active":           true,
        "license_status":              "subscribed"
  }
Result.error_msg:               "ERROR_LICENSE_NOT_FOUND"
                                "APIFEY_KEY_NOT_FOUND"

All licenses

Get all licenses issued (for caching purpose on your back-end)

POST https://gw.apifew.com/v2/app/licenses

Result.data: 
  {
    "licenses": [
      {
        "key":                  "12345678-aaaa-bbbb-cccc-1234567890abcdef",
        "active":               true,
        "status":               "subscribed",
        "end_dt":               "1970-01-01",
        },
        ...]
  }
Result.error_msg:               "APIFEY_KEY_NOT_FOUND"

Create a license

Creates 1 (or QUANTITY) license(s) for a given pricing and assign ownership to a user.
By default, will also assign usage to owner, except if optional parameter NO_USAGE is truthy.

POST https://gw.apifew.com/v2/app/pricing/license/create 

  {
    "PRICING_UID"               "ABCDEF1234567890",
    "OWNER_LOGIN"               "user1.name1@example.com"
    "QUANTITY"?                 10
    "NO_USAGE"?                 true
  }

Response (Result object) 

Result.data:
  {
    "keys":                     ["12345678-aaaa-bbbb-cccc-1234567890abcdef", ...]
  }
Result.success_msg:             "INFO_LICENSE_CREATED"
                                "INFO_LICENSE_CREATED_AND_ASSIGNED"
Result.error_msg:               "ERROR_LICENSE_CANCELLED"
                                "ERROR_MISSING_PARAMETER"
                                "ERROR_NO_LICENSE_AVAIL"
                                "ERROR_ALREADY_ASSIGNED_APP_LICENSE"
                                "ERROR_USER_NOT_FOUND"

Assign a license

Assigns usage to a user, if owner has at least 1 license available (unassigned).

POST https://gw.apifew.com/v2/app/pricing/license/assign 

  {
    "PRICING_UID"               "ABCDEF1234567890",
    "OWNER_LOGIN":              "user1.name1@example.com",
    "USER_LOGIN":               "user2.name2@example.com"
  }

Response (Result object) 

Result.data:
  {
    "key":                      "12345678-aaaa-bbbb-cccc-1234567890abcdef"
  }
Result.success_msg:             "INFO_LICENSE_ASSIGNED"
Result.error_msg:               "ERROR_LICENSE_CANCELLED"
                                "ERROR_MISSING_PARAMETER"
                                "ERROR_NO_LICENSE_AVAIL"
                                "ERROR_ALREADY_ASSIGNED_APP_LICENSE"
                                "ERROR_USER_NOT_FOUND"

Release a license

Removes usage from a user and leave it available to owner for re-assignation.

POST https://gw.apifew.com/v2/app/pricing/license/create 

  {
    "PRICING_UID"               "ABCDEF1234567890",
    "USER_LOGIN":              "user1.name1@example.com"
  }

Response (Result object) 

Result.data:
  {
    "key":                      "12345678-aaaa-bbbb-cccc-1234567890abcdef"
  }
Result.success_msg:             "INFO_LICENSE_RELEASED"
Result.error_msg:               "ERROR_MISSING_PARAMETER"
                                "ERROR_USER_NOT_FOUND"
                                "ERROR_NO_APP_LICENSE_ASSIGNED_TO_USER"

Licenses migration

Migrates all licenses related to a given pricing to pricing's latest revision

POST https://gw.apifew.com/v2/app/pricing/licenses/migrate 

  {
    "PRICING_UID"               "ABCDEF1234567890",
  }

Response (Result object) 

Result.data:
  {
    "licenses_migrated":        128
  }
Result.success_msg:             "INFO_LICENSES_MIGRATED"
Result.error_msg:               "ERROR_WRONG_PARAMETER"

Gateway to your API

Three different ways are available to serve request from end-user to your API (API provider).

Description Requested server Pros Cons
apifew's gateway gw.apifew.com simple for end-user/provider not suitable for heavy workloads
token API provider suitable for any workload more work on integration
request stamp API provider simple for end-user end-user must trust provider

apifew's gateway

It is the most straighforward. End-user requests via apifew and gets results back in a Result object. There is only 1 change vs a direct API call: request is packaged as an RPC: 

endpoint:   [POST] https://gw.apifew.com/v1/request
headers:    {
                'Content-Type':         'application/json',
                'Apifew-User-License':  '12345678-aaaa-bbbb-cccc-1234567890abcdef'
            }
body:       {
                "APP_NAME":         "api.domain.com",
                "ROUTE":            "/a/route",
                "METHOD":           "GET",
                ?"PARAMS":           {
                                        "param1":   "value1",
                                        "param2":   "value2"
                                    },
                ?"HEADERS":          {
                                        "x-api-key":    "a_secret_key"
                                    }
                ?"RESPONSE_AS_RESULT" true
            }
------------
response:   Result object (or raw response)
Result.data Response from API (if RESPONSE_AS_RESULT is true)

token

Few cases disfavor apifew's gateway option: requests involve heavy load such as picture/video or PDF files, or highly sensitive/regulated data.
In such case, API consumer needs to directly request your API.

With 'token' mode, API consumer first request a one-usage-only token to apifew, and will pass this token as header 'Apifew-Request-Token' when requesting to your API.

Step 1: consumer requests apifew for token
endpoint:   POST https://gw.apifew.com/v1/token/create
headers:
body:       { 
                "USER_LICENSE":     "<END USER LICENSE NUMBER FOR API>",
                "API_URL":          "https://exemple.api.com/route/to/request",
                "API_METHOD":       "GET"
            }
------------
response:   Result object
Result.data {
                "token":            "12345678-aaaa-bbbb-cccc-1234567890abcdef"
            }
Step 2: consumer requests API directly, with token
endpoint:       <METHOD> https://exemple.api.com/route/to/request
headers:        'Apifew-Request-Token': '12345678-aaaa-bbbb-cccc-1234567890abcdef'
params/body:    <PARAMS OR BODY>
Step 3: API provider consumes token and set request status
endpoint:   POST https://gw.apifew.com/v1/token/consume
headers:    {
                'Content-Type:      "application/json",
                'Apifew-Key':       "<API KEY (SECRET KEY DISPLAYED ON API GENERAL SETTINGS)>"
            }
body:       {
                "TOKEN":                "12345678-aaaa-bbbb-cccc-1234567890abcdef",
                "REQUEST_STATUS_CODE":  200,
    optional    "SHOW_PRICING":         true    
            }
------------
response:   Result object
Result.data {
                "app_name":         "app.api.com",
                "token":            "12345678-aaaa-bbbb-cccc-1234567890abcdef",
                "consumed":         true,
                "pricing":          "main"
            }

Warning

Note that if REQUEST_STATUS_CODE differs from 200, no fee will be charged

(optional) Step 4: consumer confirms request status

To be implemented

request stamp

This last option enables API provider to stamp request once processed

Deprecated

Users

endpoint:   
        POST https://gw.apifew.com/v1/app/user/create
body:       
    {
        "USER": {
            "login": "user.name@domain.com"
        }
    }
------------
response:
        Result object
Result.data: 
    {
        "uid":                  <USER UID FOR APPLICATION>
    }
Result.success_msg:             "INFO_APP_USER_CREATED"
Result.error_msg:               "ERROR_USER_ALREADY_EXISTS"

endpoint:   
        POST https://gw.apifew.com/v1/app/user
body:       
    {
        "USER": {
            "login": "user.name@example.com"
        }
    }
------------
response:
        Result object
Result.data: 
    {
        "login":                "user.name@example.com",
        "uid":                  "ABCDEF1234567890",
        "app":                  "app.domain.com",
        "license_number":       "12345678-aaaa-bbbb-cccc-1234567890abcdef",
        "license_ok":           true
    }
Result.error_msg:               "ERROR_USER_NOT_FOUND"

endpoint:   
        POST https://gw.apifew.com/v1/app/user/delete
body:       
    {
        "USER": {
            "login": "user.name@example.com"
        }
    }
------------
response:
        Result object
Result.success_msg:             "INFO_APP_USER_DELETED"
Result.error_msg:               "ERROR_USER_NOT_FOUND"