Introduction

Notakey Authentication Server (NtkAS) is a web based management software for the Notakey Authentication Appliance. It serves as an HTTP REST API endpoint as well. Please refer to “Notakey Authentication Appliance Administrator User Guide” for more details on platform architecture.

What’s a REST API, anyway?

An API is an application programming interface - in short, it’s a set of rules that lets programs talk to each other, exposing data and functionality across the internet in a consistent format.

REST stands for Representational State Transfer. This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term ‘REST API,’ they are generally referring to an API accessed via HTTP protocol at a predefined set of URLs.

These URLs represent various resources - any information or content accessed at that location, which can be returned as JSON, HTML, audio files, or images. Often, resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT and DELETE.

3rd-party integration

NtkAS exposes parts of its functionality via a REST HTTP-based API that is consumed both by 3rd-party software and the Notakey Authenticator. You can use either application/x-www-form-urlencoded or application/json data serilization formats for POST / PUT requests, as deserialization will be handled based on provided content type header (Content-Type) passed with request payload.

Getting Started

API consumer authentication is based on OAuth 2.0 Client Credentials authentication. Client ID and secret can be registered using Notakey Authentication Appliance (NAA) configuration shell. See NAA documentation for more details. Device API is protected by certificate based authentication with key protected by secure co-processor on mobile device and cannot be accessed outside mobile application.

API authentication

First, you have to acquire Bearer token with request like this:

Query

POST /api/token

Key	Default	Description
grant_type	none	Grant type, currently accepts “client_credentials”
client_id	none	Client identificator as set in NAA
client_secret	none	Client secret

Response

Key	Description
access_token	Access token to be used in later authentications
token_type	Token type
expires_in	Token expiry time in seconds
created_at	Token creation time in Unix timestamp

curl -X POST \
  https://demo.notakey.com/api/token \
  -d 'grant_type=client_credentials&client_id=johndeere&client_secret=p455w0rd&scope=urn:notakey:auth'
{
  "access_token": "08daac2874f6e437...9c2e646f9cc",
  "token_type": "Bearer",
  "expires_in": 3600,
  "created_at": 1543333648
}

Token parameters can be also serialized in JSON notation.

curl -X POST \
  -H "Content-Type: application/json" \
  https://demo.notakey.com/api/token \
  -d '{
     "grant_type": "client_credentials",
    "client_id": "johndeere",
    "client_secret": "p455w0rd",
    "scope": "urn:notakey:auth urn:notakey:notify" }'

{
  "access_token": "08daac2874f6e437...9c2e646f9cc",
  "token_type": "Bearer",
  "expires_in": 3600,
  "created_at": 1543333648
}

Acquired access_token token from JSON structure then can be used to make API calls as header parameter like this:

curl -X GET \
  https://demo.notakey.com/api/v3/some_api_endpoint \
  -H 'Authorization: Bearer 08daac2874f6e437...9c2e646f9cc' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

Verifying connectivity

NtkAS API provides method call for checking connectivity between service provider and API.

Plain, lightweight query to service.

$ curl -X GET https://demo.notakey.com/api/health
{"STATUS":"LIVE"}

Extended query, showing memory usage and load for load balancers, add ext to your query.

$ curl -X GET https://demo.notakey.com/api/health?ext=1
{"STATUS":"LIVE","PID":"58","VIRT":"1564024","RES":"449556","SHR":"10096","S":"S","%CPU":"0.0","%MEM":"21.9","TIME+":"3:04.99"}

Extended query, ensuring connection to backend cluster datastore, add ensure_reachable to your query.

$ curl -X GET https://demo.notakey.com/api/health?ensure_reachable=1
{"STATUS":"LIVE"}

If configuring monitoring integration, you should check always for 200 OK status. If cluster unavailable you should receive HTTP status 50x. If service is down you would see status 404. Typically all nodes should be monitored, to avoid situations where inactive node goes down unnoticed. This can be done specifying connection to node directly by IP address and passing HTTP Host header. Below is a curl equivalent of this request.

$ curl -H "Host: demo.notakey.com" https://10.0.1.99/api/health"
{"STATUS":"LIVE"}

Error handling

API generally follows HTTP status based error reporting, so when integrating you will have to observe status >= 200 and status < 300. Status 404 would mean that the referenced object does not exist while status 403 indicates authentication or authorization issues. On generic HTTP 400 error you may receive additional error message or messages in JSON payload.

{
    "errors": "Invalid value for cfkey"
}

{
    "errors": ["User over limit", "Invalid value for cfkey"]
}

Services

Query applications

Returns an array of all applications registered on NtkAS. List will include all items, but mobile application will display only the ones with at least one onboarding criteria.

Scope

none required

Request

GET /api/v3/services

Response

Key	Description
id	Applications reference path
access_id	ID of application that can be used to meke further API calls
display_name	Name of application as entered in management
logo_uri	URL of application logo
security_level	Mobile application minimum key protection level, password_protected - requires PIN / pattern protection of mobile device, software_protected - does not require additional security
onboarding_requirements.?.type	Onboarding criteria type description
onboarding_requirements.?.proof_creation_uri	URL for new onboarding request creation

curl -X GET \
  https://demo.notakey.com/api/v3/services \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

[
    {
        "id": "applications/2a435d19-a03d-4ac0-8e0e-d74a7a10e4ef/self",
        "access_id": "2a435d19-a03d-4ac0-8e0e-d74a7a10e4ef",
        "display_name": "Active Directory",
        "logo_uri": "https://demo.notakey.com/_cimg/9f0519c0-e351-4a3d-8a80-4957bf2863da",
        "security_level": "password_protected",
        "onboarding_requirements": [
            {
                "type": "UserpassOnboardingRequirement",
                "proof_creation_uri": "/applications/2a435d19-a03d-4ac0-8e0e-d74a7a10e4ef/onboarding_requirements/UserpassOnboardingRequirement/onboarding_proofs/new"
            }
        ]
    },
    {
        "id": "applications/db45a93e-81a1-4349-bcfe-d667c6ee0e81/self",
        "access_id": "db45a93e-81a1-4349-bcfe-d667c6ee0e81",
        "display_name": "Administration",
        "logo_uri": "https://demo.notakey.com/_cimg/17ea0e7b-a2de-4e27-911d-206801423c4b",
        "security_level": "password_protected",
        "onboarding_requirements": [
        ]
    },
]

Query single service

Returns attributes and onboarding requirements for specified application.

Scope

none required

Request

GET /api/v3/services/<access_id>

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request

Response

Key	Description
id	Applications reference path
access_id	ID of application that can be used to meke further API calls
display_name	Name of application as entered in management
logo_uri	URL of application logo
security_level	Mobile application minimum key protection level, see table below for details
onboarding_requirements.?.type	Onboarding criteria type description
onboarding_requirements.?.proof_creation_uri	URL for new onboarding request creation

Each service can define key protection policy as required by security policy. Table below describes each level.

Security level	Description
software_protected	Does not require additional security
password_protected	Requires PIN / pattern protection of mobile device to generate and access key. No explicit requirements for key storage
hardware_protected	Same as password_protected, but enforces key storage in TEE or similar dedicated security hardware
ratelimit_protected	Same as hardware_protected, but requires dedicated hardware with rate limited unlock attempts (only for Applie iOS devices)

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2 \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

  {
    "id": "applications/ad424756-dc35-4f78-9bbf-5a6f3367f8a3/self",
    "access_id": "ad424756-dc35-4f78-9bbf-5a6f3367f8a3",
    "display_name": "TEST App",
    "logo_uri": "https://demo.notakey.com/_cimg/fd9cd698-f5d6-4409-b659-792a01d7203c",
    "security_level": "password_protected",
    "onboarding_requirements": [
        {
            "type": "UserpassOnboardingRequirement",
            "proof_creation_uri": "/applications/cfebd2ef-0be5-4dab-b932-88adf48c65f2/onboarding_requirements/UserpassOnboardingRequirement/onboarding_proofs/new"
        }
    ]
  }

Service users

Query all service users

Scope

urn:notakey:user

Request

GET https://demo.notakey.com/api/v3/services/<access_id>/users

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request

Response

Will return array of service users

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'
  [
    {
      "keyname": "6b454c61-8aa4-49de-bcb1-a31c9c874ddd",
      "username": "demo",
      "full_name": "Example User",
      "email": "example.user@gmail.com",
      "main_phone_number": "37129551231",
      "proxied_user_keyname": null,
      "user_source_guid": null,
      "user_source_id": null,
      "max_user_device_count": 1,
      "auth_policies": [],
      "user_keyname": null,
      "teams": [],
      "enabled": true
    },
    {
        ....
    }
  ]

Query single user

Scope

urn:notakey:user

Request

GET /api/v3/services/<access_id>/users/<user_id>

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
user_id	yes	none	User ID as returned by all users query in keyname attribute

Response

Key	Format	Description
keyname	String	Unique user ID assigned by NtkAS
username	String	Username, as entered in NtkAS management
full_name	String	Full name of user
email	String	User email
main_phone_number	String	User phone
user_source_guid	String	Unique identifier in remote source
user_source_id	String	User source identifier
max_user_device_count	String	Maximum of allowed devices for user
auth_policies	Array	Array of user policies
teams	Array	Array of user teams user is a member of
groups	Array	List of user group membership
enabled	Boolean	User status

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 132...5af' \
  -H 'cache-control: no-cache'
{
    "id": "applications/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd/self",
    "keyname": "6b454c61-8aa4-49de-bcb1-a31c9c874ddd",
    "username": "demo",
    ...
}

Add new user

Scope

urn:notakey:usermanager

Request

POST /api/v3/services/<access_id>/users

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
username	yes	none	Username, as entered in NtkAS management
password	yes	none	Password for username
full_name	yes	none	Full name of user
email	no	none	User email
main_phone_number	no	none	User phone
max_user_device_count	no	1	Maximum of allowed devices for user, default taken from service definition
teams	no	[]	List of user teams
groups	no	[]	List of user group membership
enabled	no	true	User status

Response

Key	Format	Description
keyname	String	Unique user ID assigned by NtkAS
username	String	Username, as entered in NtkAS management
full_name	String	Full name of user
email	String	User email
main_phone_number	String	User phone
user_source_guid	String
user_source_id	String
max_user_device_count	Int	Maximum of allowed devices for user
auth_policies	Array	List of user policies
teams	Array	List of user teams
groups	Array	List of user group membership
enabled	Boolean	User status

curl -X POST \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 132...5af' \
  -H 'cache-control: no-cache'
  -d '
{
    "username": "example",
    "full_name": "Full name",
    "email": "example@example.com",
    "main_phone_number": "31724312423",
    "password": "wlknqjehavef@#",
    "max_user_device_count": 1,
    "teams": [],
    "groups": ["Billing"],
    "enabled": true
}''

{
    "keyname": "e203fe13-6da0-4414-95dc-57b2ab561bd0",
    "username": "example",
    "full_name": "Full name",
    "email": "example@example.com",
    "main_phone_number": "31724312423",
    "proxied_user_keyname": null,
    "user_source_guid": null,
    "user_source_id": null,
    "max_user_device_count": 1,
    "auth_policies": [],
    "user_keyname": null,
    "teams": [],
    "groups": ["Billing"],
    "enabled": true
}

Change user

Scope

urn:notakey:usermanager

Request

PUT /api/v3/services/<access_id>/users/<user_id>

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
user_id	yes	none	User ID generated by NtkAS
username	no	none	Username, as entered in NtkAS management
password	no	none	Password for username
full_name	no	none	Full name of user
email	no	none	User email
main_phone_number	no	none	User phone
max_user_device_count	no	1	Maximum of allowed devices for user, default taken from service definition
teams	no	[]	List of user teams
groups	no	[]	List of user group membership
enabled	no	true	User status

Response

Key	Format	Description
keyname	String	Unique user ID assigned by NtkAS
username	String	Username, as entered in NtkAS management
full_name	String	Full name of user
email	String	User email
main_phone_number	String	User phone
user_source_guid	String
user_source_id	String
max_user_device_count	String	Maximum of allowed devices for user
auth_policies	Array	List of user policies
teams	Array	List of user teams (used for administration service)
groups	Array	List of user group membership
enabled	Boolean	User status

curl -X PUT \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/e203fe13-6da0-4414-95dc-57b2ab561bd0 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 132...5af' \
  -H 'cache-control: no-cache'
  -d '
{
    "username": "example",
    "full_name": "Full name",
    "email": "example@example.com",
    "main_phone_number": "31724312423",
    "password": "wlknqjehavef@#",
    "max_user_device_count": 1,
    "teams": [],
    "groups": ["Manager", "Billing"],
    "enabled": true
}''

{
    "keyname": "e203fe13-6da0-4414-95dc-57b2ab561bd0",
    "username": "example",
    "full_name": "Full name",
    "email": "example@example.com",
    "main_phone_number": "31724312423",
    "proxied_user_keyname": null,
    "user_source_guid": null,
    "user_source_id": null,
    "max_user_device_count": 1,
    "auth_policies": [],
    "user_keyname": null,
    "teams": [],
    "groups": ["Manager", "Billing"],
    "enabled": true
}

Delete user

Scope

urn:notakey:usermanager

Request

DELETE /api/v3/services/<access_id>/users/<user_id>

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
user_id	yes	none	User ID generated by NtkAS

Response

Empty response with status HTTP 204 indicating success.

curl -X DELETE \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

List all user devices

Scope

urn:notakey:user

Request

GET /api/v3/services/<access_id>/users/<user_id>/devices

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
user_id	yes	none	User ID generated by NtkAS

Response

Key	Format	Description
keyname	String	Unique device ID
public_key_fingerprint	String	Fingerpint of device certificate
certificate_base_64	String	Device certificate
client_os	String	Client OS type
os_version	String	OS version number
os_locale	String	OS interface language
root_detection_status	String	Comma separated list of failed root detection tests, or NONE
model	String	Device model
manufacturer	String	Device manufacturer
app_version	String	Authenticatior app version
platform_data	String	Platform specific data

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd/devices \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'
[
    {
        "keyname": "003b76c8-ccf4-47af-86a2-9fdb93544b32",
        "public_key_fingerprint": "cf:47:e7:f7:40:81:f7:46:8d:cf:f9:e5:b4:0f:00:e5:32:6a:74:96",
        "certificate_base_64": "MIIDEjCC...Vcq5tA==\n",
        "client_os": "ios",
        "os_version": "13.1.3",
        "os_locale": "en",
        "root_detection_status": "NONE",
        "model": "iPhone XR",
        "manufacturer": "Apple",
        "app_version": "2.4.69",
        "platform_data": "{}"
    }
]

Get device by ID

Scope

urn:notakey:user

Request

GET /api/v3/services/<access_id>/users/<user_id>/devices/<device_id>

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
user_id	yes	none	User ID generated by NtkAS
device_id	yes	none	Device ID generated by NtkAS

Response

Key	Format	Description
keyname	String	Unique device ID
public_key_fingerprint	String	Fingerpint of device certificate
certificate_base_64	String	Device certificate
client_os	String	Client OS type
os_version	String	OS version number
os_locale	String	OS interface language
root_detection_status	String	Comma separated list of failed root detection tests, or NONE
model	String	Device model
manufacturer	String	Device manufacturer
app_version	String	Authenticatior app version
platform_data	String	Device identifier

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd/devices/003b76c8-ccf4-47af-86a2-9fdb93544b32 \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'
{
    "keyname": "003b76c8-ccf4-47af-86a2-9fdb93544b32",
    "public_key_fingerprint": "cf:47:e7:f7:40:81:f7:46:8d:cf:f9:e5:b4:0f:00:e5:32:6a:74:96",
    "certificate_base_64": "MIIDEjCC...Vcq5tA==\n",
    "client_os": "ios",
    "os_version": "13.1.3",
    "os_locale": "en",
    "root_detection_status": "NONE",
    "model": "iPhone XR",
    "manufacturer": "Apple",
    "app_version": "2.4.69",
    "platform_data": "{}"
}

Delete user device

Deletes specified user device and sends remote offboarding notification. This should delete service specific key from device and displays notification on user’s device. No further authentication will be possible on specified service from this device.

Scope

urn:notakey:devicemanager

Request

DELETE /api/v3/services/<access_id>/users/<user_id>/devices/

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
user_id	yes	none	User ID generated by NtkAS
device_id	yes	none	Device identifier generated by NtkAS

Response

Http status 204 in case of success.

curl -X DELETE \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd/devices/003b76c8-ccf4-47af-86a2-9fdb93544b32 \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

Get device by PKF

Fingerpint of device certificate - public key fingerprint (PKF) is usually stored with signature payload and allows fast certificate retrieval for signature validation.

Scope

urn:notakey:user

Request

GET /api/v3/services/<access_id>/pkf/<public_key_fingerprint>

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
public_key_fingerprint	yes	none	Fingerpint of device certificate

Response

Key	Format	Description
keyname	String	Unique device ID
public_key_fingerprint	String	Fingerpint of device certificate
certificate_base_64	String	Device certificate
client_os	String	Client OS type
os_version	String	OS version number
os_locale	String	OS interface language
root_detection_status	String	Comma separated list of failed root detection tests, or NONE
model	String	Device model
manufacturer	String	Device manufacturer
app_version	String	Authenticatior app version
platform_data	String	Device identifier

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/pkf/cf:47:e7:f7:40:81:f7:46:8d:cf:f9:e5:b4:0f:00:e5:32:6a:74:96 \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'
{
    "keyname": "003b76c8-ccf4-47af-86a2-9fdb93544b32",
    "public_key_fingerprint": "cf:47:e7:f7:40:81:f7:46:8d:cf:f9:e5:b4:0f:00:e5:32:6a:74:96",
    "certificate_base_64": "MIIDEjCC...Vcq5tA==\n",
    "client_os": "ios",
    "os_version": "13.1.3",
    "os_locale": "en",
    "root_detection_status": "NONE",
    "model": "iPhone XR",
    "manufacturer": "Apple",
    "app_version": "2.4.69",
    "platform_data": "{}"
}

Get user by PKF

Fingerpint of device certificate - public key fingerprint (PKF) is usually stored with signature payload and allows fast user information retrieval for signature validation.

Scope

urn:notakey:user

Request

GET /api/v3/services/<access_id>/pkf/<public_key_fingerprint>/user

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
public_key_fingerprint	yes	none	Fingerpint of device certificate

Response

Key	Format	Description
keyname	String	Unique user ID assigned by NtkAS
username	String	Username, as entered in NtkAS management
full_name	String	Full name of user
email	String	User email
main_phone_number	String	User phone
user_source_guid	String
user_source_id	String
max_user_device_count	String	Maximum of allowed devices for user
auth_policies	Array	List of user policies
teams	Array	List of user teams
enabled	Boolean	User status

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/pkf/cf:47:e7:f7:40:81:f7:46:8d:cf:f9:e5:b4:0f:00:e5:32:6a:74:96/user \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'
{
    "keyname": "e203fe13-6da0-4414-95dc-57b2ab561bd0",
    "username": "example",
    "full_name": "Full name",
    "email": "example@example.com",
    "main_phone_number": "31724312423",
    "proxied_user_keyname": null,
    "user_source_guid": null,
    "user_source_id": null,
    "max_user_device_count": 1,
    "auth_policies": [],
    "user_keyname": null,
    "teams": [],
    "enabled": true
}

Get user by username

Scope

urn:notakey:user

Request

GET /api/v3/services/<access_id>/user/<username>

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
username	yes	none	Username, as entered in NtkAS management

Response

Key	Format	Description
keyname	String	Unique user ID assigned by NtkAS
username	String	Username, as entered in NtkAS management
full_name	String	Full name of user
email	String	User email
main_phone_number	String	User phone
user_source_guid	String
user_source_id	String
max_user_device_count	String	Maximum of allowed devices for user
auth_policies	Array	List of user policies
teams	Array	List of user teams
enabled	Boolean	User status

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/user/demo \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 132...5af' \
  -H 'cache-control: no-cache'
{
    "id": "applications/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd/self",
    "keyname": "6b454c61-8aa4-49de-bcb1-a31c9c874ddd",
    "username": "demo",
    ...
}

Enable user

Scope

urn:notakey:user

Request

PUT /api/v3/services/<access_id>/users/<user_id>/enable

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
user_id	yes	none	User ID generated by NtkAS

Response

Key	Format	Description
keyname	String	Unique user ID assigned by NtkAS
username	String	Username, as entered in NtkAS management
full_name	String	Full name of user
email	String	User email
main_phone_number	String	User phone
user_source_guid	String
user_source_id	String
max_user_device_count	String	Maximum of allowed devices for user
auth_policies	Array	List of user policies
teams	Array	List of user teams
enabled	Boolean	User status

curl -X PUT \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd/enable \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'
{
  "keyname": "6b454c61-8aa4-49de-bcb1-a31c9c874ddd",
  "username": "demo",
  "full_name": "Example User",
  "email": "example.user@gmail.com",
  "main_phone_number": "37129551231",
  "proxied_user_keyname": null,
  "user_source_guid": null,
  "user_source_id": null,
  "max_user_device_count": 1,
  "auth_policies": [],
  "user_keyname": null,
  "teams": [],
  "enabled": true
}

Disable user

Scope

urn:notakey:user

Request

PUT /api/v3/services/<access_id>/users/<user_id>/disable

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
user_id	yes	none	User ID generated by NtkAS

Response

Key	Format	Description
keyname	String	Unique user ID assigned by NtkAS
username	String	Username, as entered in NtkAS management
full_name	String	Full name of user
email	String	User email
main_phone_number	String	User phone
user_source_guid	String
user_source_id	String
max_user_device_count	String	Maximum of allowed devices for user
auth_policies	Array	List of user policies
teams	Array	List of user teams
enabled	Boolean	User status

curl -X PUT \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd/disable \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'
{
  "keyname": "6b454c61-8aa4-49de-bcb1-a31c9c874ddd",
  "username": "demo",
  "full_name": "Example User",
  "email": "example.user@gmail.com",
  "main_phone_number": "37129551231",
  "proxied_user_keyname": null,
  "user_source_guid": null,
  "user_source_id": null,
  "max_user_device_count": 1,
  "auth_policies": [],
  "user_keyname": null,
  "teams": [],
  "enabled": false
}

Send messages

This API method provides a way to send a push-based informational message to end user’s all devices or SMS if user has a mobile number defined. This method avoids waking the mobile application and can be used in situations where there are issues with service functionality, e.g. service is down. Sent message payload is not encrypted and message body can be accessed by relaying agents (e.g. Google or Apple) and all applications with notification read access on mobile device.

Scope

urn:notakey:notify

Request

POST /api/v3/services/<access_id>/notify

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
username	yes	none	Username, as entered in NtkAS management, either username or user_id must be specified
user_id	yes	none	User ID as returned by all users API query, either username or user_id must be specified
title	no	none	Message title (required only for push notifications)
description	yes	none	Message body
fingerprint	no	none	Message identifier, allows to update message if sending the same fingerprint value with different body
type	no	notification	Type of message to send (sms or notification)

Response

Returns HTTP 201 if message creation successful, json error if encountered errors.

curl -X POST \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/notify \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{ "description": "test", "title": "title", "fingerprint": "test", "username": "user", "type": "notification"}'

Authentication requests

Service providers create authentication requests and then either query for status changes by UUID or wait for callback with state parameter as specified during request creation.

Create authentication request

Call this API method to send a new authentication request to selected user.

Scope

urn:notakey:auth

Request

POST /api/v3/services/<access_id>/auth

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
username	yes	none	Username, as entered in NtkAS management, either username or user_id must be specified
user_id	yes	none	User ID as returned by all users API query, either username or user_id must be specified
action	yes	none	Authentication request title in mobile app
description	yes	none	Authentication request description in mobile app
ttl_seconds	no	300	Validity duration of auth request in seconds
fingerprint	no	none	If sending auth requests to multiple failover nodes, this parameter ensures that only single unique request is sent to user
callback_url	no	none	Callback that will be invoked when response is received from mobile client
state	no	none	Parameter passed during auth request creation, allowing service provider to validate request
biometry_check	no	none	Bool value to require user to provide fingerprint or Face ID based credential
profile	no	none	Profile ID of authentication profile to use. If specified ttl_seconds, action and description are ignored
custom_vars	no	none	JSON hash of variable - value pairs to pass to auth profile and service provider (SP)
store_keys	no	none	JSON hash of variable - value to store in user profile (useful for secret storage)
fetch_keys	no	none	JSON array variable names to retreive after auth request is approved
nopush	no	false	Bool value to disable immediate push notification based auth request delivery

Response

Key	Description
id	Auth request reference path
uuid	Authentication request unique identifier

Basic request example to invoke a callback on approve or deny action:

curl -X POST \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/auth \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -d 'username=demo&action=Postman%20test&description=Postman%20test%20description&\
    fingerprint=postmanjhgfhg&ttl_seconds=11120&\
    callback_url=http%3A%2F%2Fdemo.notakey.com%3A3000%2Fcallback&state=random'
{
   "uuid": "cb32a266-fb34-4fc8-bf33-ac8268660969"
   "created_at": "2018-11-14T12:23:01Z",
   "expires_at": "2018-11-14T17:28:21.000+02:00",
   "expired": false
}

Example request to invoke authentication based on predefined authentication profile with custom variables that can be used in authentication profile and callbacks.

curl -X POST \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/auth \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
        "username": "example",
        "profile": "35683569-0f25-4514-b65f-9cc392184518",
        "custom_vars": {
            "my_service": "Some web app with MFA",
            "my_session_id": "asdfsgfrewgfd"
        }
    }'
{
   "uuid": "cb32a266-fb34-4fc8-bf33-ac8268660969"
   "created_at": "2018-11-14T12:23:01Z",
   "expires_at": "2018-11-14T17:28:21.000+02:00",
   "expired": false
}

Example to store a secret value in user’s account upon auth request approval.

curl -X POST \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/auth \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
        "username": "example",
        "action": "Credential store",
        "description": "Do you wish to store this secret?",
        "store_keys": {
            "secret": "random value"
            }
    }'
{
   "uuid": "cb32a266-fb34-4fc8-bf33-ac8268660969"
   "created_at": "2018-11-14T12:23:01Z",
   "expires_at": "2018-11-14T17:28:21.000+02:00",
   "expired": false
}

Secret value later can be retreived with this request, after it is approved. Value will be provided in kvs hash in auth request query response. See “Query authentication request” section for details.

curl -X POST \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/auth \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "username": "example",
    "action": "Credential store",
    "description": "Do you wish to give access to your secret?",
    "fetch_keys": [ "secret" ] }'
{
   "uuid": "cb32a266-fb34-4fc8-bf33-ac8268660969"
   "created_at": "2018-11-14T12:23:01Z",
   "expires_at": "2018-11-14T17:28:21.000+02:00",
   "expired": false
}

Query authentication request

Returns information about a previously-created authentication request identified by the given uuid parameter.

Scope

urn:notakey:auth

Request

GET /api/v3/services/<access_id>/auth/<uuid>

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
uuid	yes	none	Authentication request unique identifier

Response

Key	Description
id	Auth request reference path
uuid	Authentication request unique identifier
access_id	Application ID value in URL of request.
description	Authentication request description, as seen in mobile app
type	Type of request, possible values - AUTH, SIGNATURE
created_at	Creation date
expires_at	Expiry date
expired	Bool value if auth request has expired
request_ip	IP addres of auth request creator
title	Authentication request title, as seen in mobile app
action	Alias of title
logo_url	URL to logo, as seen in mobile app
logo_sash_url	URL to auth card background, as seen in mobile app
auth_request_attachments	List of attachments, if signature requested
response_payload_base64	Signed payload, empty if no response
response_type	Response state type
response_payload_type	Response envelope description
callback_url	Callback that will be invoked when response is received from mobile client
state	Parameter passed during auth request creation, allowing service provider to validate request
keytoken	Token that can be used to register public key used for encryption for this authentication session
token_used	Indicates weather keytoken above is already used
biometry_check	Boolean value specifying if biometry check was performed
groups	User group memberships, JSON array
kvs	JSON hash of requested keys specified in fetch_keys when creating auth request

Unqualified auth request query

Indicates that auth request has not been neither approved nor denied.

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/auth/cb32a266-fb34-4fc8-bf33-ac8268660969 \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

{
   "uuid": "cb32a266-fb34-4fc8-bf33-ac8268660969",
   "created_at": "2018-11-14T12:23:01Z",
   "expires_at": "2018-11-14T17:28:21.000+02:00",
   "expired": false
}

Qualified auth request query

Indicates that auth request has been approved or denied.

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/auth/cb32a266-fb34-4fc8-bf33-ac8268660969 \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

{
    "id": "archived_auth_requests/8f6dfdea-e56f-4b7e-9b6d-df60ec963cfe/self",
    "uuid": "8f6dfdea-e56f-4b7e-9b6d-df60ec963cfe",
    "access_id": "cfebd2ef-0be5-4dab-b932-88adf48c65f2",
    "description": "Postman test desc",
    "type": "AUTH",
    "created_at": "2018-12-14T12:23:01Z",
    "expires_at": "2018-12-14T17:28:21.000+02:00",
    "expired": false,
    "request_ip": "10.0.1.104",
    "title": "Demo application",
    "action": "Postman test",
    "logo_url": "/_cimg/b9037eae-4f70-4b2a-b508-475b6fd788ba?size=132x132",
    "logo_sash_url": "/_cimg/3b351e7f-232b-4d6b-9fc3-2b4247bd9b9b?size=369x60",
    "auth_request_attachments": [],
    "response_payload_base64": "PFNp..b3I+",
    "response_type": "ApproveRequest",
    "response_payload_type": "DEBUG",
    "callback_url": "http://wpdev.notakey.com:3000/callback",
    "state": "random",
    "user_id": "6b454c61-8aa4-49de-bcb1-a31c9c874ddd",
    "username": "demo",
    "full_name": "Demo user",
    "main_phone_number": "3712134324",
    "email": "demo@gmail.com",
    "keytoken": "cf7bb51f-87ea-460e-a919-a95317587bbc",
    "token_used": false,
    "kvs": {},
    "groups": [ "Billing" ]
}

Response with requested keys

When auth request includes fetch_keys array and values of keys are previously saved with store_keys parameter, response includes JSON hash of all requested keys. If a key cannot be found (e.g. it was not stored previously), specific key key will contain nil value.

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/auth/cb32a266-fb34-4fc8-bf33-ac8268660969 \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

{
    "id": "archived_auth_requests/8f6dfdea-e56f-4b7e-9b6d-df60ec963cfe/self",
    "uuid": "8f6dfdea-e56f-4b7e-9b6d-df60ec963cfe",
    "access_id": "cfebd2ef-0be5-4dab-b932-88adf48c65f2",
    "description": "Postman test desc",
    "type": "AUTH",
    "created_at": "2018-12-14T12:23:01Z",
    "expires_at": "2018-12-14T17:28:21.000+02:00",
    "expired": false,
    "request_ip": "10.0.1.104",
    "title": "Demo application",
    "action": "Postman test",
    "logo_url": "/_cimg/b9037eae-4f70-4b2a-b508-475b6fd788ba?size=132x132",
    "logo_sash_url": "/_cimg/3b351e7f-232b-4d6b-9fc3-2b4247bd9b9b?size=369x60",
    "auth_request_attachments": [],
    "response_payload_base64": "PFNp..b3I+",
    "response_type": "ApproveRequest",
    "response_payload_type": "DEBUG",
    "callback_url": "http://wpdev.notakey.com:3000/callback",
    "state": "random",
    "user_id": "6b454c61-8aa4-49de-bcb1-a31c9c874ddd",
    "username": "demo",
    "full_name": "Demo user",
    "main_phone_number": "3712134324",
    "email": "demo@gmail.com",
    "keytoken": "cf7bb51f-87ea-460e-a919-a95317587bbc",
    "token_used": false,
    "kvs": {
        "secret": "random value"
        },
    "groups": [ "Billing" ]
}

Note about response type

The response contains expiration date ( expires_at ) and response fields ( response_payload_base64 , response_type , and response_payload_type ). Unless the last three fields are all set, the response should be interpreted as unfinished:

• if the expiration time is in the past, the user did not reply and can not reply anymore.

• if the expiration time is in the future, the user may yet post a signed response (and the request should be re-checked some time in the future).

If the response_* values are set, then the user responded to the request before its expiration time (responses can only be submitted before the request expires).

Note about biometry check

If biometry check is requested, “biometry_check” will return true, but signed payload in “response_payload_base64” should also be verified to ensure that BiometryCheck has true value.

response_type possible values

Value	Description
ApproveRequest	User pressed Approve
DenyRequest	User pressed Deny

response_payload_type possible values

Value	Description
Debug	Simple signature based on XML (not an XMLDSIG) used for development purposes or low-security testing environments
Utf8Xades	Xades envelope
Utf8Cades	Cades envelope

This value is a hint as to how the response_payload_base64 should be processed.

response_payload_base64

This is the response payload envelope. It should include the request that was signed, the response (approve/deny) and the signature. This value should be first converted from base64, and then interpreted according to the response_payload_type value. This data should match the hint in response_type .

Key service

Keyservice is special purpose API exposed for PKI based key registry, that allows integrated NtkAS endpoints to securely exchange data payloads, by encrypting payload with recipient’s registered key.

User’s pubkey

Returns user’s encryption public key that can be used for payload verification and direct message encryption addressed for this user.

Request

GET /api/v3/services/<access_id>/users/<user_id>/pubkey

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
user_id	yes	none	Unique user ID assigned by NtkAS

Response

Key	Format	Description
keytype	String	Key cypher algorithm
pubkey	String	User’s registered public key
user_id	String	User unique identifier
key_uuid	String	KeyService unique identifier

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/users/6b454c61-8aa4-49de-bcb1-a31c9c874ddd/pubkey \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

{
  "keytype": "rsa-sha256",
  "pubkey": "876ujhdsjhasdk...pubkey",
  "user_id": "6b454c61-8aa4-49de-bcb1-a31c9c874ddd",
  "key_uuid": "cb32a266-fb34-4fc8-bf33-ac8268660969"
}

Key registration

Scope

urn:notakey:keyservice

Request

POST /api/v3/services/<access_id>/keys

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
keytoken	yes	none	Token from authentication request, can be used once
pubkey	yes	none	User’s registered public key PEM encoded Base64
keytype	yes	none	Key cypher algorithm

Response

Key	Description
uuid	Newly created KeyService unique identifier
expires	Expiry time in Unix timestamp

curl -X POST \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/keys \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'
  -d 'keytoken=8ff...t24&pubkey=876...87a&keytype=rsa-sha256'
{
  "uuid": "cb32a266-fb34-4fc8-bf33-ac8268660969",
  "expires": 1543406527
}

Key retrieval

Scope

urn:notakey:keyservice

Request

GET /api/v3/services/<access_id>/keys/<uuid>

Parameter	Mandatory	Default	Description
access_id	yes	none	Application ID value in URL of request
uuid	yes	none	KeyService unique identifier

Response

Key	Description
keytype	Key cypher algorithm
pubkey	User’s registered public key
user_id	User unique identifier
key_uuid	KeyService unique identifier

curl -X GET \
  https://demo.notakey.com/api/v3/services/cfebd2ef-0be5-4dab-b932-88adf48c65f2/keys/cb32a266-fb34-4fc8-bf33-ac8268660969 \
  -H 'Authorization: Bearer 132...5af' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'
{
  "keytype": "rsa-sha256",
  "pubkey": "876u...jhds",
  "user_id": "6b454c61-8aa4-49de-bcb1-a31c9c874ddd",
  "key_uuid": "cb32a266-fb34-4fc8-bf33-ac8268660969"
}

Deeplinking support

Notakey Authenticatior mobile app supports deeplinking - invoking actions in mobile app by calling app specific URI shema.

Operations supported currently are:

• authenticate

• add service domain

• autenticate with profile

• add service domain and initiate onboarding

Deeplink URIs always begin with notakey:// schema prefix, followed by qr in host field, ? sign and query parameters. Here is an example of deeplink notakey://qr?a=o&u=demo.notakey.com&k=c497894f-94d4-4354-bdc8-406888b5a616. This requests user application to add service domain demo.notakey.com and start onboarding service with ID c497894f-94d4-4354-bdc8-406888b5a616. If no such service is found, user will see an error message. Deeplink URIs can be invoked by scanning QR codes provided by NtkAS on generated by service provider with Notakey Authenticatior mobile app. URIs can also be invoked by calling them on mobile pratform from other applications.

Android intent example (broken in lines for clarity):

intent://qr?a=o&u=demo.notakey.com&k=c497894f-94d4-4354-bdc8-406888b5a616#Intent
;action=android.intent.action.VIEW
;scheme=notakey
;package=com.notakey.notakey
;end

Query parameter description

Parameter	Optional	Description
a = action	Mandatory	example: a=a. See below for details
u = service domain	Optional	example: u=demo.notakey.com. Specifies service domain to onboard. Services with SD SRV record specify plain domain values, like demo.notakey.com. If no SRV record is present, fully qualified URL has to be specified
k = service ID	Mandatory	example: k=c497894f-94d4-4354-bdc8-406888b5a616. Identifies service ID to invoke action on
s = service provider state	Optional	example: s=2cdd7b08cd3b1a0d. Needs to be specified for request origin validation on service provider side. Valid for a=a requests.
c = callback url	Optional	example: c=https%3A%2F%2Fmysp%2Fcallback. Callback to invoke after authentication request approval. Will receive state as query parameter. Valid for a=a requests.
m = action message	Optional	example: m=title. Title text for auth request. Ignored if using p param. Valid for a=a requests
d = description messge	Optional	example: d=description+text. Body text for auth request. Ignored if using p param. Valid for a=a requests.
t = timeout	Optional	example: t=300. Timeout in seconds for auth request. Ignored if using p param. Valid for a=a requests.
p = authentication profile	Optional	example: p=6b454c61-8aa4-49de-bcb1-a31c9c874ddd. Authentication profile identifier. Invokes specified authentication profile. Valid for a=a requests.
x = custom variables	Optional	example: %7B%22key%22%3A%22value%22%7D. Json encoded hash of key - value pairs to pass with auth request. Valid for a=a requests.

Action selector description

Parameter provided to key a selects the action invoked by app. Currently the following actions are supported:

Value	Description
a=a	Request authentication without push notification
a=s	Add service domain (without onboarding)
a=o	Add service domain and start onboarding for service specified in k param. Safe to call even if service domain is added already