The single preferred method of authentication to asd APIs is HMAC-based authentication.

Our APIs can use a simple shared-secret approach with a signature created according to the HMAC-SHA1 standard for authentication. You'll need a token to use HMAC-based authentication, which you can get through the Permify Panel.

Every API request requires the following two parameters:

  • hmac_timestamp
  • hmac_sign

Hmac timestamp is a current unix timestamp in UTC (integer). hmac sign is a signature generated from the URI of your request, but without the protocol or host.

Every signature has an expiration date (currently 30s). As a result, having your server time synchronized using ntp or another precise time source is critical.

For example you want to make a call to the following URL

📌 https://api.permify.co/v1/workspaces/{workspace}/users

Remove host part of the url. And add the hmac_timestamp

📌 /v1/workspaces/{workspace}/users?hmac_timestamp=1626788826

You sign this and finally append the signature:

📌 /v1/workspaces/{workspace}/users?hmac_timestamp=1626788826&hmac_sign=782d318864b31a37093320c013b595e23382e820


👍

Right hash string:

/v1/api/workspaces/{workspace}/users?hmac_timestamp=1626788826


❗️

Wrong hash string:

https://api.permify.co/v1/workspaces/{workspace_id}/users?hmac_timestamp=1626788826


Scopes

Backend

On the server side, the privite token obtained from the panel can be used (do not share this token with anyone). Private token is designed to respond to all API requests.

<?php

$host = 'https://api.permify.co'
$token = '{your-private-token}';

$path = '/v1/api/workspaces/{workspace_id}/users?type=backend';
$path = $path . '?hmac_timestamp=' . time();

$hmacSign = hash_hmac("sha1", $path, $token);

$url =  $path . "&hmac_sign=" . $hmacSign;

// make http request

?>

Frontend

On client side, public token obtained from the panel can be used (do not use the secret token on the client side). The public token is designed so that some requests (mostly http get requests) can work.

var host = 'https://api.permify.co'
var token = "{your-public-token}";
 
var path = "/v1/workspaces/{workspace}/users?type=frontend";
path = path  + "&hmac_timestamp=" + parseInt(new Date().getTime() / 1000);

var shaObj = new jsSHA("SHA-1", "TEXT");
shaObj.setHMACKey(key, "TEXT");
shaObj.update(path);

var url = path + "&hmac_sign=" + shaObj.getHMAC("HEX");