NAV Navbar

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