API Documentation

Nebulous REST API

A RESTful web API is provided that will allow users to utilize the NuID API Token, once generated. This document outlines the proper functionality of the web API, valid requests, error types, and more.

Response

The basic structure of each response will be identical. Without exception, responses must contain the following three fields: success, data, and error. The first thing to determine upon receiving the response is the success value. This will determine if you should continue to handle the data object, or handle the error object instead. The following examples show generic responses from the server in both a success and failure situation:

Success

{
    success: True,  // Indicates the request completed successfully
    data: {
        /* value depends on endpoint queried */
    },
    error: {} // Empty 
}

Failure

{
    success: False,  // Indicates the request did not complete successfully
    data: { },  // Empty
    error: {
        "ErrorName": "Helpful description of the error that occurred during the request"
    }
}

Errors

Each error offers insight into what went wrong during the request, allowing the user to change whatever.

Error Name	Description	Status Code
ActionExpired	The action you are trying to invoke has expired and is no longer valid	401
ActionInvalid	he action you are trying to invoke does not exist	401
AuthFailure	Invalid user/password combination	401
AuthMissingToken	No authentication token was provided	401
FieldMissing	One or more fields is missing from the JSON request	422
HashInvalidLength	The hash provided and the expected length for the given hash type do not match	422
HashInvalidValue	Expected hexadecimal hash representation	422
HashInvalidPrefix	A prefix must have a minimum length of 5 characters	422
HashUnsupported	The hash type provided is unsupported	422
InvalidJWT	The JWT provided was invalid	401
InvalidRequest	The request provided was malformed or missing a JSON payload	422
KeyBadUser	The API key provided does not match the expected user	401
KeyDisabled	The API key provided is disabled	403
KeyInvalid	The API key provided is invalid	401
KeyMissing	No API key was provided	401
NotFound	The endpoint you're trying to reach is invalid	404
PasswordIncorrect	The current password does not match	401
UserDisabled	The account is currently disabled	401
UserKeyLimit	You have reached the maximum number of API keys	403
UserNotActivated	The user account has not yet been activated	403
UserNotFound	The user account cannot be found	401

Supported Hashes

The following hashes are supported by Nebulous and any of these values (case insensitive) can be used in place of hash_type. The size of the hexadecimal string representation of the hash_value is also provided. The hash_prefix cannot exceed this size:

Hash	Length
MD5	32
SHA1	40
SHA256	64
NTLM	32
NTLMSHA2	64

API Endpoints

The following HTTP header must be provided on all API endpoint requests or an error will be returned:

X-NUID-API-KEY:   <Your NuID API Key>

Each endpoint begins with the following URL:

https://nebulous.nuid.io

/api/search/kanon/<hash_type>/<hash_prefix>

Method: GET Description: Query the hash database using an anonymized version of a hash. The full hash can be provided, but alternatively, a partial hash can be used in the form of a prefix that is at least 5 characters in length. All hashes in the Nebulous database matching this prefix will be returned without disclosing the exact hash itself. Response: The response from the following URL: https://nebulous.nuid.io/api/search/kanon/5f4dcc

{
  "success": true,
  "data": {
    "matches": [
      "5f4dcc3010a3b4ffd56ec97b33a0f837",
      "5f4dcc3b5aa765d61d8327deb882cf99",
      "5f4dcc3b5bef0f9cc4c0f96d758010b8"
    ]
  },
  "error": {}
}

/api/search/kanon/<hash_type>

Method: POST Post Data:

{
    "prefix": "<Hash Prefix>"
}

Description: Query the hash database using an anonymized version of a hash. The full hash can be provided, but alternatively, a partial hash can be used in the form of a prefix that is at least 5 characters in length. All hashes in the Nebulous database matching this prefix will be returned without disclosing the exact hash itself. Response: The response from the following URL: https://nebulous.nuid.io/api/search/kanon with the data {"prefix": "5f4dcc"}

{
  "success": true,
  "data": {
    "matches": [
      "5f4dcc3010a3b4ffd56ec97b33a0f837",
      "5f4dcc3b5aa765d61d8327deb882cf99",
      "5f4dcc3b5bef0f9cc4c0f96d758010b8"
    ]
  },
  "error": {}
}