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"
"name_first": "John"
"name_last": "Smith"
}
Result.error_msg: "ERROR_USER_NOT_FOUND"
User information - update
Change misc. information (first name, last name).
POST https://gw.apifew.com/v2/app/user/info/save
{
"USER_LOGIN": "user.name@example.com",
"USER_SETTINGS": {
"name_first": "John",
"name_last": "Smith"
}
}
Response (Result object)
Result.data: ["name_first", "name_last"]
Result.success_msg: "INFO::USER_INFO_SAVED"
Result.error_msg: "ERROR::USER_NOT_FOUND"
In case of success, Result.data contains field names for which the value has been modified.
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"