NAV Navbar
shell python java

Introduction

Welcome to the Cyphlens API documentation! You can use our API to access Cyphlens API endpoints, which can be used to register users, delete users, create and verify cyphs for different users.

All of our endpoints use the JSON format to send and receive data.

We have language bindings in Shell, Python, and Java! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

API base URL (sandbox): https://staging.cyphme.com/api/v1/business/

API base URL (production): https://api.cyphme.com/api/v1/business/

Authentication

To authorize, use this code:

import requests

url = "api_endpoint_here"

headers = {
  'Content-Type': 'application/json',
  'x-access-token': 'my_access_token'
}

response = requests.request("POST", url, json="", headers=headers)

# With shell, you can just pass the correct header with each request
curl -X POST "api_endpoint_here"
     -H "x-access-token: my_access_token"

Request request = new Request.Builder()
  .url("api_endpoint_here")
  .post("")
  .addHeader("Content-Type", "application/json")
  .addHeader("x-access-token", "my_access_token")
  .build();

Make sure to replace my_access_token with a valid access token.

Cyphlens uses API keys and Access Tokens to allow access to the API. You can request a new Cyphlens API key and secret via your Admin Dashboard after registration has successfully completed for your business. Also, using this dashboard, you will be able to upload your company logo and verify your connection information.

The API key and secret must be included in the API request used to obtain or renew an Access Token. Cyphlens expects for an Access Token to be included in all API requests to the server in a header that looks like the following:

x-access-token: my_access_token

Request an Access Token

import requests

url = "https://api.cyphme.com/api/v1/business/getAccessToken"

headers = {
  'Content-Type': 'application/json',
  'x-client-id': 'my_api_key',
  'x-client-secret': 'my_api_secret'
}

response = requests.request("POST", url, json="", headers=headers)

curl -X POST "https://api.cyphme.com/api/v1/business/getAccessToken"
     -H "x-client-id: my_api_key"
     -H "x-client-secret: my_api_secret"

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.cyphme.com/api/v1/business/getAccessToken")
  .post(null)
  .addHeader("Content-Type", "application/json")
  .addHeader("x-client-id", "my_api_key")
  .addHeader("x-client-secret", "my_api_secret")
  .addHeader("User-Agent", "PostmanRuntime/7.15.2")
  .addHeader("Accept", "*/*")
  .addHeader("Host", "localhost:9090")
  .addHeader("Cookie", "JSESSIONID=ABAFC73231BB05EAB247F69FXXXXXXXX")
  .addHeader("Accept-Encoding", "gzip, deflate")
  .addHeader("Content-Length", "")
  .addHeader("Connection", "keep-alive")
  .build();

Response response = client.newCall(request).execute();

Make sure to replace my_api_key and my_api_secret with your API key and secret.

On success, the above command returns JSON structured like this:

{
  "accessToken": "5c8e744eac7f44e6a1462bfXXXXXXXX",
  "expirationDate": "1564242383612"
}

Error responses have JSON structured like this:

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid client id or secret",
  "path": "/api/v1/business/getAccessToken",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid IP address",
  "path": "/api/v1/business/getAccessToken",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

This endpoint returns an Access Token to be used for all other API requests. In order to request an Access Token, you must include in this request your API key and secret in two headers that look like this:

x-client-id: my_api_key

x-client-secret: my_api_secret

HTTP Request

POST https://api.cyphme.com/api/v1/business/getAccessToken

Response Parameters

Parameter Description
accessToken The access token to use in all other API requests. Once expired, it needs to be renewed.
expirationDate Expiration date of the returned access token.

Users

Get End User Account Info

import requests

url = "https://api.cyphme.com/api/v1/business/user/get"

headers = {
  'x-access-token': '5c8e744eac7f44e6a1462bfXXXXXXXX'
}
payload = {
  'username': 'user@business.com'
}

response = requests.request("POST", url, json=payload, headers=headers)

curl -X POST "https://api.cyphme.com/api/v1/business/user/get"
     -H "x-access-token: 5c8e744eac7f44e6a1462bfXXXXXXXX"
     -d '{
           "username": "user@business.com"
     }'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");

JSONObject jsonObject = new JSONObject();
jsonObject.put("username", "user@business.com");

RequestBody body = RequestBody.create(mediaType, jsonObject.toString());
Request request = new Request.Builder()
  .url("https://api.cyphme.com/api/v1/business/user/get")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("x-access-token", "5c8e744eac7f44e6a1462bfXXXXXXXX")
  .build();

Response response = client.newCall(request).execute();

On success, the above command returns JSON structured like this:

{
  "id": "3891926237655860884",
  "businessId": "8871918765655860884",
  "status": "PENDING",
  "username": "user@business.com"
}

Error responses have JSON structured like this:

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid access token",
  "path": "/api/v1/business/user/get",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid IP address",
  "path": "/api/v1/business/user/get",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "404",
  "error": "Not Found",
  "message": "User not found",
  "path": "/api/v1/business/user/get",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

This endpoint returns the end-user Cyphlens account information, including the account status.

HTTP Request

POST https://api.cyphme.com/api/v1/business/user/get

Request Parameters

Parameter Description
username The username of the Cyphlens user account requesting information for.

Response Parameters

Parameter Description
id A unique user ID associated to the Cyphlens end-user account.
businessId The business ID associated with the Cyphlens end-user account.
status The current status of the end-user Cyphlens account.
username The username associated with the Cyphlens end-user account.

Response Parameter status

Value Description
PENDING The end-user has not yet completed the Cyphlens account activation process. End-user action is pending.
ACTIVE The end-user has an active Cyphlens account and can use all of Cyphlens services.
INACTIVE The Cyphlens account is inactive for this end-user.

Enable End User

import requests

url = "https://api.cyphme.com/api/v1/business/user/add"

headers = {
  'x-access-token': '5c8e744eac7f44e6a1462bfXXXXXXXX'
}
payload = {
  'username': 'user@business.com'
}

response = requests.request("POST", url, json=payload, headers=headers)

curl -X POST "https://api.cyphme.com/api/v1/business/user/add"
     -H "x-access-token: 5c8e744eac7f44e6a1462bfXXXXXXXX"
     -d '{
           "username": "user@business.com"
     }'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");

JSONObject jsonObject = new JSONObject();
jsonObject.put("username", "user@business.com");

RequestBody body = RequestBody.create(mediaType, jsonObject.toString());
Request request = new Request.Builder()
  .url("https://api.cyphme.com/api/v1/business/user/add")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("x-access-token", "5c8e744eac7f44e6a1462bfXXXXXXXX")
  .build();

Response response = client.newCall(request).execute();

On success, the above command returns JSON structured like this:

{
  "id": "3891926237655860884",
  "businessId": "8871918765655860884",
  "status": "PENDING",
  "username": "user@business.com"
}

Error responses have JSON structured like this:

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid access token",
  "path": "/api/v1/business/user/add",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid IP address",
  "path": "/api/v1/business/user/add",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

This endpoint enables Cyphlens services for an end-user.

HTTP Request

POST https://api.cyphme.com/api/v1/business/user/add

Request Parameters

Parameter Description
username The username of the Cyphlens user account to enable.

Response Parameters

Parameter Description
id A unique user ID for this Cyphlens user.
businessId The business ID of your business as assigned to you by Cyphlens.
status The current status of the end-user Cyphlens account.
username The username of the Cyphlens user account to enable.

Response Parameter status

Value Description
PENDING The end-user has not yet completed the Cyphlens account activation process. End-user action is pending.
ACTIVE The end-user has an active Cyphlens account and can use all of Cyphlens services.
INACTIVE The Cyphlens account is inactive for this end-user.

Delete End User

import requests

url = "https://api.cyphme.com/api/v1/business/user/delete"

headers = {
  'x-access-token': '5c8e744eac7f44e6a1462bfXXXXXXXX'
}
payload = {
  'username': 'user@business.com'
}

response = requests.request("POST", url, json=payload, headers=headers)

curl -X POST "https://api.cyphme.com/api/v1/business/user/delete"
     -H 'x-access-token: 5c8e744eac7f44e6a1462bfXXXXXXXX'
     -d '{
           "username": "user@business.com"
     }'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");

JSONObject jsonObject = new JSONObject();
jsonObject.put("username", "user@business.com");

RequestBody body = RequestBody.create(mediaType, jsonObject.toString());
Request request = new Request.Builder()
  .url("https://api.cyphme.com/api/v1/business/user/delete")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("x-access-token", "5c8e744eac7f44e6a1462bfXXXXXXXX")
  .build();

Response response = client.newCall(request).execute();

On success, the above command returns JSON structured like this:

{
  "id": "3891926237655860884",
  "businessId": "8871918765655860884",
  "status": "INACTIVE",
  "username": "user@business.com"
}

Error responses have JSON structured like this:

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid access token",
  "path": "/api/v1/business/user/delete",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid IP address",
  "path": "/api/v1/business/user/delete",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "404",
  "error": "Not Found",
  "message": "User not found",
  "path": "/api/v1/business/user/delete",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

This endpoint disables a specific end-user's Cyphlens account.

HTTP Request

POST https://api.cyphme.com/api/v1/business/user/delete

Request Parameters

Parameter Description
username The username of the Cyphlens user account to disable.

Response Parameters

Parameter Description
id A unique user ID for this Cyphlens user.
businessId The business ID of your business as assigned to you by Cyphlens.
status The current status of the end-user Cyphlens account.
username The username of the Cyphlens end-user account to disable.

Response Parameter status

Value Description
PENDING The end-user has not yet completed the Cyphlens account activation process. End-user action is pending.
ACTIVE The end-user has an active Cyphlens account and can use all of Cyphlens services.
INACTIVE The Cyphlens account is inactive for this end-user.

Cyphlens Images

Display a Cyphlens Image

Example of how to include a Cyphlens Image in a webpage.

<head>
    ...
    // Cyphlens Backend API Callback Fragment
    if (data.imageType === 'SVG') {
        $scope.imageURL = 'data:image/svg+xml;base64,' + data.image;
    } else {
        $scope.imageURL = 'data:image/png+xml;base64,' + data.image;
    }
    $scope.sessionId = data.sessionId;
    ...
</head>


<body>
    ...
    <div class="form_wrapper">
        ...
        <a href="cyphme://www.cyphme.com/verifydocument?sessionId={{sessionId}}">
            <div class="cyphlens-image">
                <img id="svg" height="210px" ng-src="{{imageURL}}"/>
            </div>
        </a>
        ...
    </div>
    ...
</body>

The sample code displayed to the right can be used to include a Cyphlens Image in a webpage as shown in the screenshot below.

Get a Login Cyphlens Image

import requests

url = "https://api.cyphme.com/api/v1/business/login/getCyph"

headers = {
  'x-auth-token': '5c8e744eac7f44e6a1462bfXXXXXXXX'
}
payload = {
  'username': 'user@business.com',
  'imageType': 'SVG'
}

response = requests.request("POST", url, json=payload, headers=headers)

curl -X POST "https://api.cyphme.com/api/v1/business/login/getCyph"
     -H "x-access-token: 5c8e744eac7f44e6a1462bfXXXXXXXX"
     -d '{
           "username": "user@business.com",
           "imageType": "SVG"
     }'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");

JSONObject jsonObject = new JSONObject();
jsonObject.put("username", "user@business.com");
jsonObject.put("imageType", "SVG");

RequestBody body = RequestBody.create(mediaType, jsonObject.toString());
Request request = new Request.Builder()
  .url("https://api.cyphme.com/api/v1/business/login/getCyph")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("x-auth-token", "5c8e744eac7f44e6a1462bfXXXXXXXX")
  .build();

Response response = client.newCall(request).execute();

On success, the above command returns JSON structured like this:

{
  "username": "user@business.com",
  "imageType": "SVG",
  "image": "PHN2ZyBiYXNlUHJvZmlsZT0idGlu...",
  "sessionId": "xcRTH3567%thASFDASvcQW"
}

Error responses have JSON structured like this:

{
  "status": "400",
  "error": "Bad Request",
  "message": "Invalid imageType",
  "path": "/api/v1/business/login/getCyph",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid access token",
  "path": "/api/v1/business/login/getCyph",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid IP address",
  "path": "/api/v1/business/login/getCyph",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "404",
  "error": "Not Found",
  "message": "User not found",
  "path": "/api/v1/business/login/getCyph",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

This endpoint generates a login Cyphlens Image for a specific end-user.

HTTP Request

POST https://api.cyphme.com/api/v1/business/login/getCyph

Request Parameters

Parameter Description
username The end-user for whom a login Cyphlens Image is being requested.
imageType The image format the Cyphlens Image should be returned as.

Request Parameter imageType

Value Description
SVG Returns a base64 encoded SVG image.
SVG_DECODED Returns a raw SVG image.
PNG Returns a base64 encoded PNG image.

Response Parameters

Parameter Description
username The username of the Cyphlens end-user account for which a login Cyphlens Image has been requested.
imageType The image format of the returned Cyphlens Image.
image The actual login Cyphlens Image encoded as per imageType parameter.
sessionId The end-user session ID associated with this login Cyphlens Image and passcode.

Verify a Login Cyphlens Image

import requests

url = "https://api.cyphme.com/api/v1/business/login/verifyCyph"

headers = {
  'x-access-token': '5c8e744eac7f44e6a1462bfXXXXXXXX'
}
payload = {
  'username': 'user@business.com',
  'passcode': '401399',
  'sessionId': '\xcRTH3567%thASFDASvcQW'
}

response = requests.request("POST", url, json=payload, headers=headers)

curl -X POST "https://api.cyphme.com/api/v1/business/login/verifyCyph"
     -H 'x-access-token: 5c8e744eac7f44e6a1462bfXXXXXXXX'
     -d '{
           "username": "user@business.com",
           "passcode": "401399",
           "sessionId": "xcRTH3567%thASFDASvcQW"
     }'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");

JSONObject jsonObject = new JSONObject();
jsonObject.put("username", "user@business.com");
jsonObject.put("passcode", "401399");
jsonObject.put("sessionId", "xcRTH3567%thASFDASvcQW");

RequestBody body = RequestBody.create(mediaType, jsonObject.toString());
Request request = new Request.Builder()
  .url("https://api.cyphme.com/api/v1/business/login/verifyCyph")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("x-access-token", "5c8e744eac7f44e6a1462bfXXXXXXXX")
  .build();

Response response = client.newCall(request).execute();

On success, the above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "message": "Verification successful."
}

{
  "status": "FAILURE",
  "message": "Verification failure. Passcode invalid."
}

Error responses have JSON structured like this:

{
  "status": "400",
  "error": "Bad Request",
  "message": "Invalid passcode",
  "path": "/api/v1/business/login/verifyCyph",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid access token",
  "path": "/api/v1/business/login/verifyCyph",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid IP address",
  "path": "/api/v1/business/login/verifyCyph",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

{
  "status": "404",
  "error": "Not Found",
  "message": "User not found",
  "path": "/api/v1/business/login/verifyCyph",
  "timestamp": "2024-03-25T10:33:11.857+0000"
}

This endpoint verifies the passcode of a login Cyphlens Image for a specific end-user.

HTTP Request

POST https://api.cyphme.com/api/v1/business/login/verifyCyph

Request Parameters

Parameter Description
username The end-user for whom a login Cyphlens Image is being verified.
passcode The passcode to verify sent by the end-user.
sessionId The end-user session ID associated with this login Cyphlens Image and passcode.

Response Parameters

Parameter Description
status The outcome of the verification request.
message Some descriptive text.

Response Parameter status

Value Description
SUCCESS The passcode provided by the end-user has been successfully verified.
FAILURE The passcode provided by the end-user is wrong.
400 The passcode is missing.
401 Either the access token or the IP address is invalid.
404 End-user not found.

Errors

The Cyphlens API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request has some invalid or missing data.
401 Unauthorized -- Either your API key is wrong, your access token is wrong or your IP address is invalid.
404 Not Found -- The specified end-user could not be found.
405 Method Not Allowed -- You tried to access the Cyphlens API with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're sending too many requests! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell python java