Skip to main content

Decipher Support

All the topics, resources needed for Decipher.


FocusVision Knowledge Base

Decipher REST API 2.0


The Decipher REST API is the tool for automating your workflow with the Decipher platform. It enables you to efficiently send and request resources to and from any project that you are working on. Registered Decipher users can access the API via web calls, or via a Python library package that, once installed, enables you to integrate with the Decipher services you have access to.

Whether accessing the API via a web call, or through the Decipher Python Package, you will need to generate an API key for your user.

Generating an API Key

In order to access the Beacon API externally, you will need to generate an API key for your user through the Research Hub. To generate an API key, access the Research Hub and select "API Access" from the System Tools menu (click your profile image / avatar):


This will take you to the API access page listing all users who have generated API keys.


Any user listed on this page will also have their public key displayed. Note that the public key alone is not enough to make Beacon API calls, as each user needs their full key that only they have access to in order to do so.In order to create a brand new key for you user, you can select the "Create new API key" option. This take you through several steps before you get your key.

First, you need to specify the user for which you want to generate the key. You can either enter the username of the user or input self if you are generating a key for yourself:


Next, enter any desired restrictions or click "OK" to continue:


You will then receive a 64-character API key that you can use to authenticate your API calls:


The API key consists of two parts. The first 32 characters are your public key that display on the main API page, while the second 32 characters are your private key that will never be listed anywhere. In order to make API calls, the full 64 characters must be passed through.

Note: Make sure that you copy the full key and keep it in a safe place. Do not share this key with anyone. The API key logs and represents your user when making API calls, so anyone who has it can access projects as if they were you.

Once you grab your API key, your user will be added to the list of available keys on the main API page:


This page will display only your public key, so you won’t be able to grab the full key from this page. If you no longer have your full key, you have the option to generate a new key by clicking the "rekey" option. You also have the option to delete the API key for your user, if you no longer wish to use it.

API Call Permissions

The API key will allow you to execute only the API's that your user account has permissions to run. For example, if a certain user has "View Only" access to a project, they will not be able to access a 'Data Edit' API call. Likewise, if a user is not a Supervisor, they will not be able to execute an API call to retrieve a list of all users for a company.

While a user with a valid key will be able to execute any API call, if they attempt to execute a call they do not have permission to run, they will receive a "403 INVALID AUTHORIZATION" error code instead of the expected result.

The following is an example of the '403' error code response:

curl --header 'x-apikey: 6xd513ar9uvh4vw05de41dkc08h60c6xp6xj4eb3ma7hkdenejcp3ghxkwrmr8se' ‘’
"$error": "you cannot do this",
"$code": 403,
"extra": null

Note: Click here to learn more about user permissions within Decipher.

Accessing the API

From a Linux System

Installing the API Python package

To access the API, you will first need to download and install the Decipher API Python Library package. For users with their own private cloud servers, the API Python library is installed by default, and can be accessed via the shell.

If you are accessing the API via some other Linux system, you can install the Decipher API Python library using the following command:

sudo pip install decipher

This Python library includes a script named "beacon" that can run from the command line and is used to easily connect with the API.

Once the library is installed, you can type beacon into your command line to view its usage details:

user@domain:~$ beacon
beacon [options] <verb> <resource> [arg=value...]
Verb is one of:
get    -- list resources
post   -- create new resource
put    -- update existing resource
delete -- delete or retire existing resource
login  -- interactively define an API key and host
rekey -- rekey your current secret key and update the config file

Extra arguments are decoded as JSON objects/arrays if they start with { or [

-v verbose (show headers sent & received))
-t display output as an aligned text table
-x display output as IBM JSON XML
-p display Python code required to make the call
-s <section> use a different section in the /home/user/.config/decipher file than 'main'
-V <version> use a different API version

Authentication and Authorization

The Decipher API will only respond to authorized users. To become authorized, you must first generate an API key that will be authenticated by the system.

Note: For Decipher Cloud customers, authentication happens automatically with your shell credentials if running the commands via the command line. There is no need to login with the steps below.

Type beacon login into your shell terminal to view the methods for authenticating with the system:

How do you want to authenticate?
1. Enter the 64-character API key (valid until deactivated)
2. Enter your username/password (temporary login)
3. Enter a long code (visible on the API key page)
q. Quit
Select 1, 2, 3 or q: 1

1. API key authentication - Using this method, you only need to authenticate once. Once you provide your API key, it will be saved under your Linux user’s config settings, and it will be automatically provided when you use the beacon command.


API KEY: *provide your 64 character key here*

Enter your host, or press Enter for the default
Testing your new settings...
Looks good. Settings were saved to the file /home/user/.config/decipher

As illustrated above, when providing your API key, you will be asked to enter the "Host" for which it has been generated. This is the domain that you use to log into Decipher. For example, if you use to access the platform, your host name will be "".

2. Username / password login - This method allows you to login with your Decipher username and password, and will generate a temporary API key for you. Similar to the API key authentication method, you need to specify the host name of the server where you wish to log in.


Enter your full username (email address)
Enter your password
Password: password
Enter your host, or press Enter for the default
Testing your new settings...
Acquired a temporary session key. It will be expire after 25403883 minutes of idle time.
Looks good. Settings were saved to the file /home/user/.config/decipher

Note: The above method only creates a temporary key for your current session.

3. Generating a temporary key - Selecting option 3 allows you to login with a temporary key generated from the API page in the Decipher application:


Clicking the "generate temporary key" hyperlink will give you a new API key:


You can then input that key when prompted.


Temporary Key: *your temporary key here*
Testing your new settings...
Looks good. Settings were saved to the file /home/pagov/.config/decipher

Note: The recommended way of authentication when using the Decipher REST API is to use a permanent API key

Executing API Calls from the Command Line

The beacon script lets you run API calls directly from the command line. Depending on the API call, you can use the beacon script to execute GET, POST, PUT or DELETE requests.

Example GET:

beacon get rh/users

The above command uses a GET method to return a list of all users for a specific company or server.

Note: This command requires the user to have a Decipher Cloud account.

Example PUT:

beacon put rh/users/4504 active=false

The above command uses a PUT method to change the active property to false, thus disabling the user.

Example POST:

beacon post surveys/selfserve/214e/180100/sst count=200 qualified=true

The above command uses a POST method to run simulated test data for the selfserve/214e/180100 project. The "count" argument being passed through sets the number of test data to run, while the "qualified" flag tells the system to submit mostly qualified runs.

Example DELETE:

beacon delete rh/apikeys/aj8vzu9ze9r6nv7yyqy3g5u0970960qfaj8vzu9ze9r6nv7yyqy3g5u0970960qf

Executing API Calls in a Python script

From the command line, you can also pass the -p flag through a beacon command to review the corresponding Python syntax. You can then place that syntax in a Python script file to automate the execution of an API call.


beacon -p get rh/users select=id,login,fullname,last_login_where sort=-last_login_where limit=10

The above command will not execute the API call, but will instead provide you with the following syntax:

from decipher.beacon import api
result = api.get('rh/users', sort="-last_login_where", limit="10", select="id,login,fullname,last_login_where")
print result

You can then paste the above output directly in a Python script.

Using Web Calls

You can also access the Decipher API via a web call utility, as you would any web-based API. One such utility is cURL, which is used for all the following examples.

Note: General Information about cURL can be found here.


All web calls must include your API key in the x-apikey header.

Note: The username / password authentication method is not available when using web calls.

Example 1:

curl --header "x-apikey: API_KEY" ''

The above command is used to access a list of all the currently implemented API endpoints in Decipher.

Note: You need to surround your API call URL in single quotes, in order to ensure that any special characters get escaped properly

Note: If using other methods to make a web call, you need to make sure that they are able to pass in the x-apikey header as part of your request.

Executing Web Calls

The main difference between using the beacon package and executing web calls is that web calls will need the full URL to the API endpoint you wish to access. For example, running the users API call will require you to add extra information to the API endpoint definition.

beacon Package Example:

beacon get rh/users/4504 active=false

cURL (Web Call) Example:

curl --header "x-apikey: API_KEY”

Apart from adding the host name of the server where your project is situated, you also need to add in api/v1 as part of your API endpoint reference, to explicitly tell the system to access the API.

Web Request Examples (Using cURL)

Example GET:

The following command can be used to test out the “Hello Service” endpoint to test out the API system:

curl --header "x-apikey: API_KEY"

The example above will return a JSON object as a response:

{"ok": "1", "hello": "FunFunFun"}

Example POST:

Reproducing the same POST command executed earlier with the beacon package will require the following syntax:

- curl --header "x-apikey: API_KEY" -X post

Note that when passing in additional parameters to the API call, you need to add them as URL parameters to the end of the API endpoint. The first parameter you add should be prefixed with ? (?count=200), while any additional parameters should be prefixed with & (&qualified=true).

Note: cURL commands default to using the GET method. To specify a different request method, you must use the -X flag.

Example POST With Data:

Some API calls require you to pass data back through to Decipher. For example, data edits / imports done through an API call may require you to pass the data to import through in JSON format. When using JSON, you must make sure you pass through the correct content type and use the proper syntax, which includes adding double quotes around the various items within the JSON object:

curl -X POST -H 'Content-Type: application/json' -H "x-apikey: MY_API_KEY" '' -d '{"data": [{"Q1": 1}]}'

In the above cURL command, several modifiers are used to pass through the information needed to successfully execute the API call.

First, the -X flag is used to specify which method to use for the API call. Then, two -H flags are included - one to add multiple headers to the request. The x-apikey header will hold the API key, and the Content-Type header tells the system that the information will be sent over in a JSON file format. Meanwhile, the -d flag is used to pass through the actual data, and it is followed by the JSON object that contains what is needed to send to the API.

Note: As previously mentioned, any API web call method you use should be able to support the above functionalities, which include adding multiple headers, the ability to specify a web call method (GET, POST, PUT, and DELETE), and the ability to pass in data objects as part of the call.

Decipher API Python Library Page

Click here to view the full documentation for the Decipher REST API Python package.

Full Decipher API Endpoints List

Click here to view the Decipher REST API reference page. This link will include all current and future API resources available with the Decipher REST API.

Response Codes and Error States

The following HTTP response codes are returned when making a request to the Decipher API:





Your data is in the response body.



Your API key is invalid, expired, or not valid from this IP address or for this action.



You have exceeded your available API calls.



Your API key is valid but you are not allowed access to this survey.



You asked for a survey or resource that does not exist.



You tried to perform an action that was not allowed (e.g., delete something that does not support deletion).



Please wait a moment and try your request again.



Resources do not implement this method. Are you using GET / POST / PUT / DELETE?



Something else went wrong (e.g., the survey cannot be loaded due to an error).

Note: The "402" response code is not currently utilized.

  • Was this article helpful?