API Reference
- Documentation Overview
- Quick Start Examples
- Authentication
- User Object
- Run Object
- GET /api/runs/
- POST /api/runs/
- GET /api/runs/{id}/
- POST /api/runs/{id}/cancel/
- GET /api/runs/{id}/sdd-report/
- Option Object (Referenced in the
/runs/
POST Request)
- Runlog Object
- Connection Object
- Connection Fileset Object
- Ruleset Object
- Seed Object
- Audit Log Object
- Generate ruleset
- Generate Ruleset Result Object
- Oracle Wallets
- Git Related Endpoints
- Other API Requests
Documentation Overview
This API Reference documentation page provides details on how to use the DataMasque API.
If you're new to working with REST APIs, please read the Quickstart Examples section, which provide an overview of using Postman and curl
.
Otherwise, check the index listed above to quickly access documentation as well as curl
examples for each endpoint.
Quickstart Examples
The examples on this page use
<
and>
as delimiters for example values, but these characters should not be used in the requests.
Preface
These examples are made for beginners new to using REST APIs.
We'll guide you step by step on how to use Postman and curl
to interact with the DataMasque API.
Remember, the type of request (GET
, POST
, PUT
, etc.) depends on what is specified in our documentation for each endpoint.
An Overview of Making Requests With Postman
Please note that this documentation is based on Postman version 10.22. Future or previous versions of Postman may have slightly different options or behaviors.
Aside from the Postman example listed in the Authentication section, this is the only Postman example. However, a
curl
example will be listed for each endpoint.
Open Postman: Launch the Postman application on your device.
Create a New Request:
- At the top of your window, select the File menu tab, then select New.
- At modal will appear which will ask what type of request is needed. Select HTTP.
Set the Request Method:
- Above the URL field, you'll see a dropdown menu. This is where you specify the type of request (
GET
,POST
,PUT
, etc.) as indicated in our documentation for the endpoint you are using.
- Above the URL field, you'll see a dropdown menu. This is where you specify the type of request (
Enter the URL:
- In the URL field, type
https://<your-datamasque-host>/<your-desired-endpoint>/
. - Replace
<your-datamasque-host>
and<your-desired-endpoint>
with the appropriate values provided in our documentation.
- In the URL field, type
Set Headers (For
POST
/PUT
Requests):- If the request type is
POST
orPUT
, you'll need to set some additional headers. - Go to the Headers tab just below the URL field.
- Add two keys:
Content-Type
andAccept
. For both, set the value toapplication/json
, unless specified as a different value in that endpoint's documentation.
- If the request type is
Add Request Body (For
POST
/PUT
Requests):
Sometimes a request body needs to be specified for sending special types of request parameters to the DataMasque API. One example of is this is during the API Token retrieval request. When makingPUT
orPOST
requests, check the endpoint's documentation listed on this page to see if a request body is needed.- Switch to the Body tab.
- Select
raw
and chooseJSON
from the dropdown menu that appears. - Enter the JSON-formatted data as specified in our documentation.
Authorization (If Required):
- Some requests might require an authorization token.
- In the Headers tab, add a new key
Authorization
. - Set its value to
Token <your-api-token>
, replacing<your-api-token>
with your actual token.
Send the Request:
- Click the Send button to dispatch your request.
Check the Response
- Under the Response section which takes up half of the My Workspace window in Postman, take a look at the returned response body under the Body tab.
- If the response body is empty, take a look at the Status header to the right of the response section.
- There should be a numerical code e.g.
200
followed by some text. If the text is notOK
and the status code is400
is higher, check the Body tab's returned JSON object to see if any error details have been specified. - If there are no error details returned in the response body, check if the status code next to the Status header is one listed in the Common Failiure Responses of our API documentation. This details provided there should give more insight into what may have caused the error.
- If the status code is not listed there, refer to the endpoint's section of this documentation for any endpoint-specific error codes and their details.
An Overview of Making Requests With curl
Please note that this documentation is based on
curl
version 8.50.0. Future or previous versions ofcurl
may have slightly different options or behaviors.
Open Your Command Line Interface:
- Access your terminal on macOS or Linux, or your command prompt or PowerShell on Windows.
Construct Your Request:
- Start by typing
curl
. This is the basic command to use the curl tool. - Specify the request method by adding
-X
request followed by the method (POST
,PUT
, etc.) as indicated in our documentation for the endpoint you are using. If the request method isGET
, you do not need to include the-X
flag.
- Start by typing
Enter the URL:
- After
-X <METHOD>
, type the full URL of the API endpoint you wish to call.
- After
Set Headers:
- For sending headers with your request, use the
-H
flag followed by the header in quotes. - For most requests, especially
POST
orPUT
, set theContent-Type
andAccept
headers toapplication/json
, unless specified as a different value in that endpoint's documentation.
- For sending headers with your request, use the
Add Request Body (For
POST
/PUT
Requests):- When the request type is
POST
orPUT
, and you need to send data, use the-d
option followed by the data in JSON format. - Ensure you've checked the endpoint's documentation to verify if a request body is needed.
- When the request type is
Include Authorization Token (If Required):
- If an endpoint requires an authorization token, add it to the headers using the
-H
flag. - For example,
-H "Authorization: Token <your-api-token>"
, replacing<your-api-token>
with the actual token you received from the token retrieval endpoint.
- If an endpoint requires an authorization token, add it to the headers using the
Send the Request:
- After constructing the full
curl
command with all the necessary flags and data, press Enter to send the request.
- After constructing the full
Check the Response:
- The response will be printed directly in the terminal. Review the response body and headers to ensure your request was successful.
Quickstart generic example with curl
curl -X <GET | POST | PUT | DELETE> "https://<your-datamasque-host>/<your-desired-endpoint>/" \
-H "Authorization: Token <your-api-token>" \
-H "<your-additional-headers>"
Common Responses
Upon making a request, as part of the HTTP response, you will receive a status code and potentially some details about the success status of the request made.
Most successful request response status codes will be in the range 200
to 299
.
For each endpoint detailed in this documentation, their expected success status codes and descriptions are listed.
However, when a response is not successful, there are several common failure response status codes which are useful to be aware of.
There may be several status codes which deviate from the ones mentioned in the following section, however, these will be listed in this documentation under specific endpoint sections.
Common Failure Responses
Status Code | Description |
---|---|
400 |
Bad Request: Check the JSON body and response for more information. |
401 |
Unauthorized: Token required. |
403 |
Forbidden: User is not allowed. |
404 |
Not Found. |
Authentication
The DataMasque API uses token authentication.
Tokens are 40-character strings containing 0-9 and a-f.
Tokens should be included in the Authorization
HTTP header for each request,
with the word Token
prepended.
For example
GET /runs/123/
Authorization: Token abcdef1234567890abcdef1234567890abcdef12
There are two types of authentication tokens:
- A non-expiring API Token which has access to only some endpoints. You can get this token from the My Account page.
- A User Token that is valid for only 12 hours, but has access to all endpoints.
User tokens are granted by posting your username and password to the
/api/auth/token/login/
endpoint.
The documentation for each endpoint on this page includes the type of token that is required to access it.
If an endpoint does not require the use of the Authorization
header then its authorization is noted as Anonymous.
The purpose and use case of each token type is explained below.
API Token
The API Token is a long-lived credential retrieved from the My Account page. It remains valid indefinitely, unless revoked (also on the My Account page). This token is valid only for use with specific API endpoints.
It is designed to be used in automated scripts whose content may not be stored securely, therefore it mainly has access to controlling masking runs and checking their status.
User Token
The User Token is exclusively issued after a successful login,
either through the user interface or by making a request to /api/auth/token/login/
.
This token offers enhanced security due to its limited lifetime, expiring after 12 hours, and is only accessible after a successful login. When accessing DataMasque through the UI, the token is granted as a cookie which will expire after 1 hour of inactivity.
It can be used against all API endpoints, and grants access based on the user account's permissions.
Both token types serve distinct purposes within the DataMasque API, offering a balance between security and usability.
POST /api/auth/token/login/
Authorization: Anonymous.
Login with a username and password to obtain a user_token
.
POST /api/auth/token/login/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
username |
string |
Yes | Request Body | The username of the user you are logging in as. |
password |
string |
Yes | Request Body | The password for the user. |
POST /api/auth/token/login/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised user object, including a short-lived API key. |
POST /api/auth/token/login/ Postman example
- Open Postman.
- Create a new request.
- Set the method to
POST
and the URL tohttps://<your-datamasque-host>/auth/token/login/
. - Under Headers, add
Content-Type
as a key and set the value asapplication/json
. - Select the Body tab then the raw button.
- Include your DataMasque login details in this format in the text editor shown:
{
"username": "<your-username>",
"password": "<your-password>"
}
- Press the blue Send button to the right of the URL bar.
POST /api/auth/token/login/ curl
example
curl -X POST "https://<your-datamasque-host>/api/auth/token/login/" \
-H "Content-Type: application/json" \
-d '{"username": "<your-username>", "password": "<your-password>"}'
User Object
User
objects have the following fields:
Field | Type | Description |
---|---|---|
id |
integer |
The id of the User . |
username |
string |
The username for the User . Used when logging in. |
email |
string |
The email of the User . |
date_joined |
date |
The date the User was created. |
api_token |
string |
The API token for the User . |
has_temporary_password |
boolean |
Whether user has a temporary password or not. If true, the user has not finalised their account creation. |
is_active |
boolean |
Whether or not the user account is active. If false, the account is disabled. |
is_staff |
boolean |
Whether or not the user is a staff account. |
is_superuser |
boolean |
Whether or not the account is a superuser and has admin privileges. |
is_sso_user |
boolean |
Whether or not the account is an SSO enabled account. |
is_subscribed_to_sdd_updates |
boolean |
Whether or not the user has subscribed to sensitive data discovery updates. |
- Requests related to User Object:
GET /api/users/
Authorization: User token only.
Returns a list of user accounts.
GET /api/users/ Parameters
No parameters.
GET /api/users/ Responses
Status Code | Description |
---|---|
200 |
Returns a JSON serialised list of User objects. |
GET /api/users/ Parameters
No parameters.
GET /api/users/ curl
example
curl GET "https://<your-datamasque-host>/api/users/" \
-H "Authorization: Token <your-api-token>"
GET /api/users/me/
Authorization: User token only.
Returns the details of the currently logged-in user.
GET /api/users/me/ Responses
Status Code | Description |
---|---|
200 |
Returns a JSON serialised User object for the user that is currently logged in. |
GET /api/users/me/ curl
example
curl GET "https://<your-datamasque-host>/api/users/me/" \
-H "Authorization: Token <your-api-token>"
Run Object
Run
objects have the following fields:
Field | Type | Description |
---|---|---|
id |
integer |
The id of the Run . Use this in API URLs that need a run id . |
name |
string |
The name of the Run . |
status |
string |
The status of the Run . The potential values are: queued , running , finished , failed , cancelling , and cancelled . A status of finished indicates a run completed successfully; failed indicates an error. |
mask_type |
string |
The masking type of the Run , valid options are "database" or "file" . |
connection |
string |
Deprecated, replaced by source_connection . |
connection_name |
string |
Deprecated, replaced by source_connection_name . |
source_connection |
string |
A UUID identifying the source connection used for this Run . For database connections, the source_connection also acts as the destination. |
source_connection_name |
string |
The name of the source connection of the Run . For database connections, the source_connection also acts as the destination. |
destination_connection |
Optional[string] |
A UUID identifying the destination connection used for this Run . Only present for file connections, as the source_connection also acts as the destination for database connections. |
destination_connection_name |
Optional[string] |
The name of the destination connection of the Run . Only present for file connections, as the source_connection also acts as the destination for database connections. |
ruleset |
string |
A UUID identifying the ruleset used for this Run . |
ruleset_name |
string |
Ruleset name of the Run . |
start_time |
string |
Start time of the Run , in iso format. |
end_time |
string |
End time of the Run , in iso format. |
options |
object |
An Option object of configuration for the Run . |
- Requests related to Run Objects:
- GET /api/runs/
- POST /api/runs/
- GET /api/runs/{id}/
- POST /api/runs/{id}/cancel/
- GET /api/runs/{id}/sdd-report/
- Option Object (Referenced in the
/api/runs/
POST Request)
GET /api/runs/
Authorization: User token or API token.
Get a list of DataMasque Runs.
GET /api/runs/ Parameters
No parameters.
GET /api/runs/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised list of Run objects. |
GET /api/runs/ curl
example
curl GET "https://<your-datamasque-host>/api/runs/" \
-H "Authorization: Token <your-api-token>"
POST /api/runs/
Authorization: User token or API token.
Start a new masking run.
POST /api/runs/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
name |
string |
Yes | Request Body | The name of the Run . |
connection |
string |
No | Request Body | Deprecated, replaced by source_connection . |
source_connection |
string |
Yes | Request Body | A UUID identifying the source connection to be used for this Run . For database connections, the source_connection also acts as the destination. |
destination_connection |
string |
No, Only required for runs on file connections. | Request Body | A UUID identifying the connection to be used for this Run . |
ruleset |
string |
Yes | Request Body | A UUID identifying the ruleset to be used for this Run . |
options |
object |
Yes | Request Body | An Option object of configuration for this Run . |
POST /api/runs/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised Run object. |
POST /api/runs/ curl
example
curl -X POST "https://<your-datamasque-host>/api/runs/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "<run-name>",
"source_connection": "<source-connection-uuid>",
"destination_connection": "<destination-connection-uuid>", # Include this only if required
"ruleset": "<ruleset-uuid>",
"options": {
#... option object details ...
}
}'
GET /api/runs/{id}/
Authorization: User token or API token.
Retrieve information about a masking run.
GET /api/runs/{id}/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
id |
integer |
Yes | URL Path | The id of the Run . |
GET /api/runs/{id}/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised Run object. |
GET /api/runs/{id}/ curl
example
curl GET "https://<your-datamasque-host>/api/runs/{id}/" \
-H "Authorization: Token <your-api-token>"
POST /api/runs/{id}/cancel/
Authorization: User token or API token.
Cancel a masking run.
POST /api/runs/{id}/cancel/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
id |
integer |
Yes | URL Path | The id of the Run . |
POST /api/runs/{id}/cancel/ Responses
Status Code | Description |
---|---|
201 |
Operation succeeded |
POST /api/runs/{id}/cancel/ curl
example
curl -X POST "https://<your-datamasque-host>/api/runs/{id}/cancel/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json"
GET /api/runs/{id}/sdd-report/
Authorization: User token only.
A binary serialised SDD Report object.
GET /api/runs/{id}/sdd-report/ Parameters
No parameters.
GET /api/runs/{id}/sdd-report/ Responses
Status Code | Description |
---|---|
200 |
The server will return the SDD Report in the response body which can be downloaded as a CSV file. |
404 |
If there is no SDD Report for a run, the server will return 404 status code. |
GET /api/runs/{id}/sdd-report/ curl
example
curl GET "https://<your-datamasque-host>/api/runs/{id}/sdd-report/" \
-H "Authorization: Token <your-api-token>"
Option Object
Option
objects have the following fields:
Field | Type | Description |
---|---|---|
batch_size |
integer |
An argument to specify the number of rows to fetch in each batch retrieved from the database for masking. This is ignored for file masking. |
dry_run |
boolean |
Indicates a dry run where no data in the database is actually changed. Values should either be true to indicate a dry run, or false to run normally. Default value is false . More information on dry runs is available in the Masking runs documentation. |
max_rows |
integer |
A parameter to specify the maximum number of rows that will be masked by each mask_table task1. Defaults to no limit. This is ignored for file masking. |
continue_on_failure |
boolean |
If there is a task failure, and this option is false , DataMasque will skip all remaining unstarted tasks. If this option is true , DataMasque will continue performing other tasks even if there is a task failure. Default value is false . |
run_secret |
string |
The run secret is used in the random generation of masked values. If left unspecified, a random secret will be automatically generated and returned in the API response 2. Masking runs performed on the same DataMasque instance with the same run secret will produce the same masked values for identical unmasked database inputs. You should only specify a run secret if you require consistent masking across runs, otherwise it is more secure to allow a new run secret to be automatically generated for each run. Run secrets must be at least 20 characters long. |
disable_instance_secret |
boolean |
If this option is set to true , DataMasque will exclude its instance-specific secret and generate masked values based solely on the run secret. You may wish to disable the instance in order to achieve consistent masking across DataMasque instances. However, by disabling the instance secret, any DataMasque instance using the same run_secret could replicate your data masking. |
buffer_size (deprecated; will be removed in release 3.0.0) |
integer |
Replaced by batch_size . |
1
max_rows
does not apply tomask_unique_key
tasks.2 The
run_secret
contained in the API response can be provided in subsequent API calls to start runs, facilitating consistent masking across those runs.
Additionally, the following options apply to schema discovery runs (i.e. runs that include at least one run_schema_discovery
task):
Field | Type | Description |
---|---|---|
custom_keywords |
list[string] |
List of keywords that, where a column's name matches one or more of the keywords, indicates the column contains sensitive data. Default value is an empty list. |
ignored_keywords |
list[string] |
List of keywords that, where a column's name matches one or more of the keywords, indicates the column should be excluded from the schema discovery results. Default value is an empty list. |
disable_global_custom_keywords |
boolean |
If set to true , then the user-defined global set of custom keywords will not be used to flag columns as sensitive. Default value is false . |
disable_global_ignored_keywords |
boolean |
If set to true , then the user-defined global set of ignored keywords will not be used to exclude columns from the schema discovery results. Default value is false . |
disable_built_in_keywords |
boolean |
If set to true , then DataMasque's built-in list of keywords will not be used to flag columns as sensitive. Default value is false . |
schemas |
list[string] |
List of schema (database for MySQL/MariaDB) names against which to perform schema discovery. Default value is an empty list, meaning schema discovery will run against the schema configured on the database connection, or the database user's default schema. Default value is an empty list. |
- Requests related to Option Object:
Runlog Object
Runlog
objects have the following fields:
Field | Type | Description |
---|---|---|
run |
integer |
ID of the Run this Runlog was generated for. |
worker_id |
string |
ID of the masking worker that generated this Runlog . |
timestamp |
string |
Timestamp of this Runlog 's generation, in ISO format. |
message |
string |
The log message passed from the masking worker. |
args |
string |
Arguments passed to the Run task. |
run_status |
string |
Indicates the Run status. The potential values are: queued , running , finished , failed , cancelling , and cancelled . A status of finished indicates the Run completed successfully; failed indicates an error. |
is_dry_run |
boolean |
Indicates whether the Run is a dry run. |
- Requests related to Runlog Object:
GET /api/runs/{id}/log/
Authorization: User token or API token.
List all logs for a specified Run
.
GET /api/runs/{id}/log/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
id |
integer |
Yes | URL Path | The id of the Run . |
GET /api/runs/{id}/log/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised list of Runlog objects. |
GET /api/runs/{id}/log/ curl
example
curl GET "https://<your-datamasque-host>/api/runs/{id}/log/" \
-H "Authorization: Token <your-api-token>"
Connection Object
Database Connection
objects have the following fields:
Field | Type | Description |
---|---|---|
version |
string |
The connection version. This should be set to `1.0'. |
id |
integer |
The id of the Connection . Use this in API URLs that need a connection id . |
name |
string |
The name of the Connection . |
user |
string |
The name of the user in the database connection. |
db_type |
string |
The type of database the connection is connecting to. |
database |
string |
The database the connection is connecting to. |
host |
string |
The hostname of the database connection. |
port |
integer |
The database port being connected through. |
dbpassword |
string |
The password for the user connecting to the database. |
schema |
string |
The schema of the database to connect to. (Optional) |
options |
object |
An Option object of configuration for the Run |
service_name |
string |
The service name for the connection. Only used for Oracle. (Optional) |
connection_fileset |
string |
The connection fileset attached to this connection. Currently only used for MySQL and MariaDB. (Optional) |
mask_type |
string |
The type of masking the connection can perform, only database or file are valid. (Optional) Should be set to database for database Connections . |
last_discovery_run_date |
string |
The created_time of the last run on this connection including a run_schema_discovery task, or null if no such run has been performed. |
last_discovery_run_id |
string |
The ID of the last run on this connection including a run_schema_discovery task, or null if no such run has been performed. |
File Connection
objects have the following fields:
Field | Type | Description |
---|---|---|
version |
string |
The connection version. This should be set to `1.0'. |
id |
integer |
The id of the Connection . Use this in API URLs that need a connection id . |
name |
string |
The name of the Connection . |
type |
string |
The type of file system the connection is connecting to. Valid options are "s3_connection" , "azure_blob_connection" or "mounted_share_connection" . |
base_directory |
string |
The root file path where files intended to be masked are stored. |
bucket |
string |
The name of the S3 bucket containing the base_directory . Only for S3 Connections . |
container |
string |
The name of the Azure Blob Storage container containing the base_directory . Only for Azure Blob Connections . |
connection_string |
string |
The connection string configured with the authorization information to access data in your Azure Storage account. Only for Azure Blob Connections . |
mask_type |
string |
The type of masking the connection can perform, only database or file are valid. (Optional) Should be set to file for file Connections . |
is_file_mask_source |
boolean |
A boolean if the connection is a source Connection for file masking. (Optional) Defaults to false if not provided. |
is_file_mask_destination |
boolean |
A boolean if the connection is a destination Connection for file masking. (Optional) Defaults to false if not provided. |
- Requests related to Connection Object:
GET /api/connections/
Authorization: User token only.
Get a list of all DataMasque connections.
Optionally, you can add an {id}
to the end of the request to only return the details of the connection with that
specific id
.
GET /api/connections/ Parameters
Can optionally follow the URL with the id
of a specific connection to only return information on that connection.
GET /api/connections/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised Connection object. |
Quickstart example using curl
curl GET "https://<your-datamasque-host>/api/connections/" \
-H "Authorization: Token <your-api-token>"
POST /api/connections/
Authorization: User token only.
Create a new connection object.
POST /api/connections/ Parameters
Database Connections
Field | Type | Required | Location | Description |
---|---|---|---|---|
version |
string |
Yes | Request Body | The connection version. This should be set to 1.0 . |
name |
string |
Yes | Request Body | The name of the Connection . |
user |
string |
Yes | Request Body | The name of the user in the database connection. |
db_type |
string |
Yes | Request Body | The type of database the connection is connecting to. |
database |
string |
Yes | Request Body | The database the connection is connecting to. |
host |
string |
Yes | Request Body | The hostname of the database connection. |
port |
integer |
Yes | Request Body | The database port being connected through. |
dbpassword |
string |
Yes | Request Body | The password for the user connecting to the database. |
schema |
string |
No | Request Body | The schema of the database to connect to. |
service_name |
string |
No, Only used for Oracle. | Request Body | The service name for the connection. |
connection_fileset |
string |
No, Only used for MySQL and MariaDB. | Request Body | The connection fileset attached to this connection. |
mask_type |
string |
No, Defaults to database if not provided. |
Request Body | The type of masking the connection can perform, only database or file are valid. |
File Connections
Field | Type | Required | Location | Description |
---|---|---|---|---|
version |
string |
Yes | Request Body | The connection version. This should be set to `1.0'. |
name |
string |
Yes | Request Body | The name of the Connection . |
type |
string |
Yes | Request Body | The type of file system the connection is connecting to. Valid options are "s3_connection" , "azure_blob_connection" or "mounted_share_connection" . |
base_directory |
string |
Yes | Request Body | The root file path where files intended to be masked are stored. |
bucket |
string |
No, Only for S3 Connections . |
Request Body | The name of the S3 bucket containing the base_directory . |
container |
string |
No, Only for Azure Blob Connections . |
Request Body | The name of the Azure Blob Storage container containing the base_directory . |
connection_string |
string |
No, Only for Azure Blob Connections . |
Request Body | The connection string configured with the authorization information to access data in your Azure Storage account. |
mask_type |
string |
No, Defaults to database if not provided. |
Request Body | The type of masking the connection can perform, only database or file are valid. |
is_file_mask_source |
boolean |
No, Defaults to false if not provided. |
Request Body | A boolean if the connection is a source Connection for file masking. |
is_file_mask_destination |
boolean |
No, Defaults to false if not provided. |
Request Body | A boolean if the connection is a destination Connection for file masking. |
POST /api/connections/ Responses
Status Code | Description |
---|---|
201 |
A JSON serialised Connection object. |
POST /api/connections/ curl
example
curl -X POST "https://<your-datamasque-host>/api/connections/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-d '{
"version": "1.0",
"name": "<connection_name>",
"user": "<database_user>",
"db_type": "<database_type>",
"database": "<database_name>",
"host": "<database_host>",
"port": <database_port>,
"password": "<database_password>",
"schema": "<database_schema>",
"service_name": "<oracle_service_name>",
"connection_fileset": "<connection_fileset>",
"mask_type": "database"
}'
PUT /api/connections/{id}/
Authorization: User token only.
Update a connection with a specified id with new values.
PUT /api/connections/{id}/ Parameters
Database Connections
Field | Type | Required | Location | Description |
---|---|---|---|---|
version |
string |
Yes | Request Body | The connection version. This should be set to 1.0 . |
name |
string |
Yes | Request Body | The name of the Connection . |
user |
string |
Yes | Request Body | The name of the user in the database connection. |
db_type |
string |
Yes | Request Body | The type of database the connection is connecting to. |
database |
string |
Yes | Request Body | The database the connection is connecting to. |
host |
string |
Yes | Request Body | The hostname of the database connection. |
port |
integer |
Yes | Request Body | The database port being connected through. |
dbpassword |
string |
Yes | Request Body | The password for the user connecting to the database. |
schema |
string |
No | Request Body | The schema of the database to connect to. |
service_name |
string |
No, Only used for Oracle. | Request Body | The service name for the connection. |
connection_fileset |
string |
No, Only used for MySQL and MariaDB. | Request Body | The connection fileset attached to this connection. |
mask_type |
string |
No, Defaults to database if not provided. |
Request Body | The type of masking the connection can perform, only database or file are valid. |
File Connections
Field | Type | Required | Location | Description |
---|---|---|---|---|
version |
string |
Yes | Request Body | The connection version. This should be set to `1.0'. |
name |
string |
Yes | Request Body | The name of the Connection . |
type |
string |
Yes | Request Body | The type of file system the connection is connecting to. Valid options are "s3_connection" , "azure_blob_connection" or "mounted_share_connection" . |
base_directory |
string |
Yes | Request Body | The root file path where files intended to be masked are stored. |
bucket |
string |
No, Only for S3 Connections . |
Request Body | The name of the S3 bucket containing the base_directory . |
container |
string |
No, Only for Azure Blob Connections . |
Request Body | The name of the Azure Blob Storage container containing the base_directory . |
connection_string |
string |
No, Only for Azure Blob Connections . |
Request Body | The connection string configured with the authorization information to access data in your Azure Storage account. |
mask_type |
string |
No, Defaults to database if not provided. |
Request Body | The type of masking the connection can perform, only database or file are valid. |
is_file_mask_source |
boolean |
No, Defaults to false if not provided. |
Request Body | A boolean if the connection is a source Connection for file masking. |
is_file_mask_destination |
boolean |
No, Defaults to false if not provided. |
Request Body | A boolean if the connection is a destination Connection for file masking. |
PUT /api/connections/{id}/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised Connection object with the new updated values. |
PUT /api/connections/{id}/ curl
example
curl -X PUT "https://<your-datamasque-host>/api/connections/{connection_id}/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-d '{
"version": "1.0",
"name": "<connection_name>",
"user": "<database_user>",
"db_type": "<database_type>",
"database": "<database_name>",
"host": "<database_host>",
"port": <database_port>,
"password": "<database_password>",
"schema": "<database_schema>",
"service_name": "<oracle_service_name>",
"connection_fileset": "<connection_fileset>",
"mask_type": "database"
}'
DELETE /api/connections/{id}/
Authorization: User token only.
Delete the connection with the specified id.
DELETE /api/connections/{id}/ Parameters
No parameters.
DELETE /api/connections/{id}/ Responses
Status Code | Description |
---|---|
204 |
Operation succeeded |
DELETE /api/connections/{id}/ curl
example
curl -X DELETE "https://<your-datamasque-host>/api/connections/{id}/" \
-H "Authorization: Token <your-api-token>"
POST /api/connections/test/
Authorization: User token only.
Test a connection to validate that it is able to successfully connect to the target database.
POST /api/connections/test/ Parameters
Database Connections
Field | Type | Required | Location | Description |
---|---|---|---|---|
version |
string |
Yes | Request Body | The connection version. This should be set to 1.0 . |
name |
string |
Yes | Request Body | The name of the Connection . |
user |
string |
Yes | Request Body | The name of the user in the database connection. |
db_type |
string |
Yes | Request Body | The type of database the connection is connecting to. |
database |
string |
Yes | Request Body | The database the connection is connecting to. |
host |
string |
Yes | Request Body | The hostname of the database connection. |
port |
integer |
Yes | Request Body | The database port being connected through. |
dbpassword |
string |
Yes | Request Body | The password for the user connecting to the database. |
schema |
string |
No | Request Body | The schema of the database to connect to. |
service_name |
string |
No, Only used for Oracle. | Request Body | The service name for the connection. |
connection_fileset |
string |
No, Only used for MySQL and MariaDB. | Request Body | The connection fileset attached to this connection. |
File Connections
Field | Type | Required | Location | Description |
---|---|---|---|---|
version |
string |
Yes | Request Body | The connection version. This should be set to `1.0'. |
name |
string |
Yes | Request Body | The name of the Connection . |
type |
string |
Yes | Request Body | The type of file system the connection is connecting to. Valid options are "s3_connection" , "azure_blob_connection" or "mounted_share_connection" . |
base_directory |
string |
Yes | Request Body | The root file path where files intended to be masked are stored. |
bucket |
string |
No, Only for S3 Connections . |
Request Body | The name of the S3 bucket containing the base_directory . |
container |
string |
No, Only for Azure Blob Connections . |
Request Body | The name of the Azure Blob Storage container containing the base_directory . |
connection_string |
string |
No, Only for Azure Blob Connections . |
Request Body | The connection string configured with the authorization information to access data in your Azure Storage account. |
mask_type |
string |
No, Defaults to database if not provided. |
Request Body | The type of masking the connection can perform, only database or file are valid. |
is_file_mask_source |
boolean |
No, Defaults to false if not provided. |
Request Body | A boolean if the connection is a source Connection for file masking. |
is_file_mask_destination |
boolean |
No, Defaults to false if not provided. |
Request Body | A boolean if the connection is a destination Connection for file masking. |
POST /api/connections/test/ Responses
Status Code | Description |
---|---|
204 |
Operation succeeded |
Connection Fileset Object
Connection Fileset
objects have the following fields:
Field | Type | Description |
---|---|---|
id |
integer |
The id of the Connection Fileset . Use this in API URLs that need a connection_fileset id . |
name |
string |
The name of the Connection Fileset . |
database_type |
string |
The type of database the Connection Fileset is associated with (currently only mysql is supported; this will work with both MySQL and MariaDB connections). |
zip_archive |
string |
The location of the zip archive. |
- Requests related to Connection Fileset:
POST /api/connections/test/ curl
example
curl -X POST "https://<your-datamasque-host>/api/connections/test/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "<your-connection-name>",
"user": "<your-connection-user>",
"db_type": "oracle",
"database": "<your-database>",
"host": "<your-host>",
"port": 1433,
"dbpassword": "<your-password>",
"schema": "<optional-schema>",
"service_name": "<optional-service-name>",
"connection_fileset": "<optional-connection-fileset>",
"version": "1.0"
}'
GET /api/connection-filesets/
Authorization: User token only.
Returns a list of Connection Filesets. These may be used to encrypt connections to MySQL and MariaDB databases.
GET /api/connection-filesets/ Parameters
No parameters.
GET /api/connection-filesets/ Responses
Status Code | Description |
---|---|
201 |
A list of JSON serialised Connection Filesets. |
GET /api/connection-filesets/ curl
example
curl GET "https://<your-datamasque-host>/api/connection-filesets/" \
-H "Authorization: Token <your-api-token>"
POST /api/connection-filesets/
Authorization: User token only.
Create a new Connection Fileset.
POST /api/connection-filesets/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
name |
string |
Yes | Form Field | The name of the Connection Fileset . |
database_type |
string |
Yes | Form Field | The type of database the Connection Fileset is associated with (currently only mysql is supported; this will work with both MySQL and MariaDB connections). |
zip_archive |
file |
Yes | Form Field | The zip archive file. |
POST /api/connection-filesets/ Responses
Status Code | Description |
---|---|
201 |
A JSON serialised object of the Connection Fileset that was created. |
POST /api/connection-filesets/ curl
example
curl -X POST "https://<your-datamasque-host>/api/connection-filesets/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-F "name=<fileset_name>" \
-F "database_type=<database_type>" \
-F "zip_archive=@</path/to/your/file.zip>"
PUT /api/connection-filesets/{id}/
Authorization: User token only.
Update a Connection Fileset.
PUT /api/connection-filesets/{id}/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
name |
string |
Yes | Form Field | The name of the Connection Fileset . |
database_type |
string |
Yes | Form Field | The type of database the Connection Fileset is associated with (currently only mysql is supported; this will work with both MySQL and MariaDB connections). |
zip_archive |
file |
Yes | Form Field | The zip archive file. |
PUT /api/connection-filesets/{id}/ Responses
Status Code | Description |
---|---|
201 |
A JSON serialised object of the Connection Fileset that was created. |
PUT /api/connection-filesets/{id}/ curl
example
curl -X PUT "https://<your-datamasque-host>/api/connection-filesets/{id}/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-F "name=<fileset_name>" \
-F "database_type=<database_type>" \
-F "zip_archive=@</path/to/your/file.zip>"
DELETE /api/connection-filesets/{id}/
Authorization: User token only.
Deletes the Connection Fileset with the specified id
. You may not delete a Connection Fileset associated to an
existing connection.
DELETE /api/connection-filesets/{id}/ Parameters
No parameters.
DELETE /api/connection-filesets/{id}/ Responses
Status Code | Description |
---|---|
204 |
Operation succeeded. |
DELETE /api/connection-filesets/{id}/ curl
example
curl -X DELETE "https://<your-datamasque-host>/api/connection-filesets/{id}/" \
-H "Authorization: Token <your-api-token>"
`
Ruleset Object
Ruleset
objects have the following fields:
Field | Type | Description |
---|---|---|
id |
integer |
The id of the Ruleset . Use this in API URLs that need a ruleset id . |
name |
string |
The name of the Ruleset . |
config_yaml |
string |
The contents of the Ruleset , including of all the masking rules. |
is_valid |
boolean |
Whether or not the Ruleset is valid, and can be used for masking runs. |
mask_type |
string |
The masking type of the Ruleset . This can be "database" or "file" . |
- Requests related to Ruleset Object:
GET /api/rulesets/
Authorization: User token only.
Returns a list of all rulesets.
GET /api/rulesets/ Parameters
No parameters.
GET /api/rulesets/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised list of Ruleset objects. |
GET /api/rulesets/ curl
example
curl GET "https://<your-datamasque-host>/api/rulesets/" \
-H "Authorization: Token <your-api-token>"
GET /api/rulesets/{id}/
GET /api/rulesets/{id}/ Parameters
No parameters.
GET /api/rulesets/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised Ruleset object. |
curl GET "https://<your-datamasque-host>/api/rulesets/{id}/" \
-H "Authorization: Token <your-api-token>"
POST /api/rulesets/
Authorization: User token only.
Creates a new ruleset.
POST /api/rulesets/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
name |
string |
Yes | Request Body | The name of the Ruleset . |
config_yaml |
string |
Yes | Request Body | The YAML contents of the Ruleset . |
mask_type |
string |
No | Request Body | The masking type of the Ruleset . Valid options are "database" or "file" . |
POST /api/rulesets/ Responses
Status Code | Description |
---|---|
201 |
A JSON serialised Ruleset object. |
POST /api/rulesets/ curl
example
curl -X POST "https://<your-datamasque-host>/api/rulesets/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "<your-new-name>",
"config_yaml": "version: \"1.0\"\ntasks:\n - type: run_data_discovery"
}'
PUT /api/rulesets/{id}/
Authorization: User token only.
Update an existing ruleset.
PUT /api/rulesets/{id}/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
name |
string |
Yes | Request Body | The name of the Ruleset . |
config_yaml |
string |
Yes | Request Body | The YAML contents of the Ruleset . |
mask_type |
string |
No | Request Body | The masking type of the Ruleset . Valid options are "database" or "file" . |
PUT /api/rulesets/{id}/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised Ruleset object with the updated values. |
PUT /api/rulesets/{id}/ curl
example
curl -X PUT "https://<your-datamasque-host>/api/rulesets/{id}/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "<your-new-name>",
"config_yaml": "version: \"1.0\"\ntasks:\n - type: run_data_discovery"
}'
DELETE /api/rulesets/{id}/
Authorization: User token only.
Deletes the ruleset with the specified id
.
DELETE /api/rulesets/{id}/ Parameters
No parameters.
DELETE /api/rulesets/{id}/ Responses
Status Code | Description |
---|---|
200 |
Operation succeeded |
DELETE /api/rulesets/{id}/ curl
example
curl -X DELETE "https://<your-datamasque-host>/api/rulesets/{id}/" \
-H "Authorization: Token <your-api-token>" \
Seed Object
Field | Type | Description |
---|---|---|
id |
integer |
The id of the Seed . |
name |
string |
The name of the Seed . |
seed_file |
string |
The location of the Seed . |
created date |
datetime |
The date that the Seed was uploaded. |
filename |
string |
The file name of the uploaded Seed . |
- Requests that use Seed Object:
GET /api/seeds/
Authorization: User token only.
Get a list of all DataMasque seed files.
Optionally, you can add an {id}
to the end of the request to only return the details of the seed with that specific
id
.
GET /api/seeds/ Parameters
No parameters.
GET /api/seeds/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised list of Seed objects. |
GET /api/seeds/ curl
example
curl GET "https://<your-datamasque-host>/api/seeds/" \
-H "Authorization: Token <your-api-token>"
POST /api/seeds/
Authorization: User token only.
Create a new seed from a csv file.
POST /api/seeds/ Parameters
Field | Type | Required | Description |
---|---|---|---|
name |
string |
No | The name of the csv file. |
description |
string |
No | A description of the seed file to displayed on the files menu. |
seed_file |
file |
No | The seed file. |
POST /api/seeds/ Responses
Status Code | Description |
---|---|
201 |
A JSON serialised Seed object. |
POST /api/seeds/ curl
example
curl -X POST "https://<your-datamasque-host>/api/seeds/" \
-H "Authorization: Token <your-api-token>" \
-F "name=<fileset_name>" \
-F "seed_file=@</path/to/your/seed_file.csv>"
Audit Log Object
Field | Type | Description |
---|---|---|
id |
integer |
The id of the audit log. |
timestamp |
datetime |
The timestamp of when the audit log was created. |
username |
string |
The username which created the audit log. |
category |
string |
The category for the audit log, one of the following: auth , run , ruleset , or connection |
action |
string |
The action taken. One of the following: logged_in logged_out , for auth actions, started , cancelled , for masking run actions, created , modified , deleted for connection or ruleset actions. |
description |
string |
A short description of what happened during the action. |
- Requests that use Audit Log Object:
Audit Log CSV
A CSV representation of the Audit Log Object
The CSV file contains the following headers:
Field | Type | Description |
---|---|---|
timestamp |
datetime |
The timestamp of when the audit log was created. |
username |
string |
The username which created the audit log. |
category |
string |
The category for the audit log, one of the following: auth , run , ruleset , or connection |
action |
string |
The action taken. One of the following: logged_in logged_out , for auth actions, started , cancelled , for masking run actions, created , modified , deleted for connection or ruleset actions. |
description |
string |
A short description of what happened during the action. |
- Requests that use Audit Log CSV:
GET /api/audit-logs/
Authorization: User token only.
Retrieve all Audit Logs.
GET /api/audit-logs/ Parameters
No parameters.
GET /api/audit-logs/ Response
Status Code | Description |
---|---|
200 |
A list of JSON serialised list of Audit Log objects |
GET /api/audit-logs/ curl
example
curl GET "https://<your-datamasque-host>/api/audit-logs/" \
-H "Authorization: Token <your-api-token>"
GET /api/audit-logs/download/
Authorization: User token only.
Retrieve all Audit Logs.
GET /api/audit-logs/download/ Parameters
No parameters.
GET /api/audit-logs/download/ Response
Status Code | Description |
---|---|
200 |
The server will return the audit logs in the response body which can be then downloaded as a CSV file. |
GET /api/audit-logs/download/ curl
example
curl -o <your-downloads-path>/<your-download-name>.csv -X GET "https://<your-datamasque-host>/api/audit-logs/" \
-H "Authorization: Token <your-api-token>"
POST /api/generate-ruleset/
Authorization: User token only.
Returns a ruleset string for selected columns of a connection.
Prerequisite: Make sure you have the schema-discovery report for the connection sepecified in the post data.
Generate Ruleset Result Object
Generate Ruleset Result
objects have the following fields:
Field | Type | Description |
---|---|---|
id |
integer |
The id of the Generate Ruleset Result . |
connection_id |
string |
The ID of the connection we have generated ruleset on. |
generated_ruleset |
string |
The ruleset that have been generated. |
status |
string |
The status of the generating ruleset progress. |
error_message |
string |
The error message when generating ruleset failed. |
- Requests that use Generate Ruleset Result Object:
POST /api/generate-ruleset/ curl
example
curl -X POST "https://<your-datamasque-host>/api/generate-ruleset/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-d '{
"connection": "<your-connection-id>",
"selected_columns": {
"schema_name": {
"table_name": [
"column_name_1",
"column_name_2"
]
}
}
}'
GET /api/async-generate-ruleset/{connection_id}/
Authorization: User token only.
Returns result of generating ruleset progress.
GET /api/async-generate-ruleset/{connection_id}/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
connection_id |
string |
Yes | URL Path | The id of the Connection . |
GET /api/async-generate-ruleset/{connection_id}/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised Generate Ruleset Result Object. |
GET /api/async-generate-ruleset/{connection_id}/ curl
example
curl GET "https://<your-datamasque-host>/api/async-generate-ruleset/{connection_id}/" \
-H "Authorization: Token <your-api-token>"
POST /api/async-generate-ruleset/{connection_id}/
Authorization: User token only.
Start generating ruleset for selected columns of a connection.
POST /api/async-generate-ruleset/{connection_id}/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
connection_id |
string |
Yes | URL Path | The id of the Connection . |
POST /api/async-generate-ruleset/{connection_id}/ curl
example
curl -X POST "https://<your-datamasque-host>/api/async-generate-ruleset/{connection_id}/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-d '{
"selected_columns": {
"schema_name": {
"table_name": [
"column_name_1",
"column_name_2"
]
}
}
}'
GET /api/oracle-wallets/
Authorization: User token only.
Returns a list of Oracle wallets. These are used to connect to encrypted Oracle connections.
GET /api/oracle-wallets/ Parameters
No parameters.
GET /api/oracle-wallets/ Responses
Status Code | Description |
---|---|
201 |
A JSON serialised list of Oracle wallets. |
GET /api/oracle-wallets/ curl
example
curl GET "https://<your-datamasque-host>/api/oracle-wallets/" \
-H "Authorization: Token <your-api-token>"
POST /api/oracle-wallets/
Authorization: User token only.
Create a new Oracle wallet.
POST /api/oracle-wallets/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
name |
string |
Yes | Form Field | The name of the Oracle Wallet. |
zip_archive |
file |
Yes | Form Field | The zip archive file. |
POST /api/oracle-wallets/ Responses
Status Code | Description |
---|---|
201 |
A JSON serialised Oracle wallet object of the wallet created. |
POST /api/oracle-wallets/ curl
example
curl -X POST "https://<your-datamasque-host>/api/oracle-wallets/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-F "name=<fileset_name>" \
-F "zip_archive=@</path/to/your/file.zip>"
DELETE /api/oracle-wallets/{id}/
Authorization: User token only.
Delete the Oracle wallet with the specified id.
DELETE /api/oracle-wallets/{id}/ Parameters
No parameters.
DELETE /api/oracle-wallets/{id}/ Responses
Status Code | Description |
---|---|
204 |
Operation succeeded. |
DELETE /api/oracle-wallets/{id}/ curl
example
curl -X DELETE "https://<your-datamasque-host>/api/oracle-wallets/{id}/" \
-H "Authorization: Token <your-api-token>"
Git Related Endpoints
Git Setting Object
Git settings are global for the DataMasque instance and can only be updated by an admin user. Git settings are updated on the Settings page in the DataMasque UI.
Git Setting
objects have the following fields:
Field | Type | Description |
---|---|---|
git_repository_url |
string |
The URL of where the Git repository is hosted. |
git_branch |
string |
The name of the Git branch from which DataMasque will push or pull. |
git_directory_path |
string |
The directory that DataMasque will push and pull rulesets to, relative to the root of the repository. Note that DataMasque does not support pushing/pulling rulesets in subdirectories of this directory. |
GET /api/git-setting/
Authorization: User token only.
Retrieve a Git Setting Object with information about the DataMasque instance's Git settings.
GET /api/git-setting/ Parameters
No parameters.
GET /api/git-setting/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialized Git Setting Object for the DataMasque instance. |
GET /api/git-setting/ curl
example
curl GET "https://<your-datamasque-host>/api/git-setting/" \
-H "Authorization: Token <your-api-token>"
SSH Key Object
SSH Key
objects have the following fields:
Field | Type | Description |
---|---|---|
name |
string |
The specified filename of the SSH Key file. |
date_uploaded |
string |
The ISO 8601 datetime string of when the user uploaded the SSH key. |
GET /api/git-ssh-key/
Authorization: User token only.
Retrieve an SSH Key Object for information about the current user's uploaded SSH Key.
GET /api/git-ssh-key/ Parameters
No parameters.
GET /api/git-ssh-key/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialized SSH Key Object which is the most recent SSH Key Upload for the user which made the request. |
GET /api/git-ssh-key/ curl
example
curl GET "https://<your-datamasque-host>/api/git-ssh-key/" \
-H "Authorization: Token <your-api-token>"
PUT /api/git-ssh-key/
Authorization: User token only.
Upload an SSH Key to be used to access a Git remote repository.
Warning: A user may have only one SSH key at a time, so the existing key will be deleted and replaced with the uploaded key for the user making the request.
PUT /api/git-ssh-key/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
key_file |
file |
Yes | Form Field | The SSH Key file. |
name |
string |
Yes | Form Field | The name of the file. |
PUT /api/git-ssh-key/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialized SSH Key Object, which is the most recent SSH Key Upload for the user making the request. |
PUT /api/git-ssh-key/ curl
example
curl -X PUT "https://<your-datamasque-host>/api/git-ssh-key/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-F "key_file=@</path/to/your/file>" \
-F "name=<your-ssh-key-filename>"
DELETE /api/git-ssh-key/
Authorization: User token only.
Delete the current user's uploaded SSH key.
DELETE /api/git-ssh-key/ Parameters
No parameters.
DELETE /api/git-ssh-key/ Responses
Status Code | Description |
---|---|
204 |
The SSH key associated with the requesting user has been deleted. |
DELETE /api/git-ssh-key/ curl
example
curl DELETE -X "https://<your-datamasque-host>/api/git-ssh-key/" \
-H "Authorization: Token <your-api-token>"
GET /api/ruleset-git/
Authorization: User token only.
Pull the content of a specific ruleset given its commit ID. The current user's Git SSH key is used for authentication.
How File Paths Are Built
Internally, DataMasque generates the name of the file by appending .yml
to ruleset_name
.
The file name is then appended to git_directory_path
(from the DataMasque Git Settings)
to build the full file path.
For example, for a ruleset_name
of My Ruleset
and git_directory_path
of masking/rulesets
,
the file masking/rulesets/My Ruleset.yml
will be retrieved.
Its contents will be that as at the specified commit ID.
GET /api/ruleset-git/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
commit_id |
string |
Yes | Query Param | The Git commit ID for the ruleset. |
ruleset_name |
string |
Yes | Query Param | The name of the ruleset. Used to build the path as per How File Paths Are Built above. |
GET /api/ruleset-git/ Responses
Status Code | Description |
---|---|
200 |
A JSON object with a single key, config_yaml , that contains the ruleset content |
GET /api/ruleset-git/ curl
example
curl GET "https://<your-datamasque-host>/api/ruleset-git/?commit_id=<your-full-commit-id>&ruleset_name=<your-ruleset-name>" \
-H "Authorization: Token <your-api-token>"
POST /api/ruleset-git/
Authorization: User token only.
Commit then push changes upstream for a specific ruleset.
POST /api/ruleset-git/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
commit_message |
string |
Yes | Request Body | The Git commit message for the ruleset changes. |
ruleset_name |
string |
Yes | Request Body | The name of the ruleset. Used to build the path as per How File Paths Are Built above. |
ruleset_content |
string |
Yes | Request Body | The YAML contents of the ruleset. |
POST /api/ruleset-git/ Responses
Status Code | Description |
---|---|
200 |
Operation succeeded. |
POST /api/ruleset-git/ curl
example
curl -X POST "https://<your-datamasque-host>/api/ruleset-git/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-d '{
"commit_message": "Update ruleset",
"ruleset_name": "<your-ruleset-filename>",
"ruleset_content": "version: \"1.0\"\ntasks:\n - type: run_data_discovery"
}'
GET /api/ruleset-git/files/
Authorization: User token only.
This endpoint lists the git_directory_path
in the remote repository configured for the DataMasque instance.
It considers any files ending in .yml
to be ruleset files,
and will fetch the list of commits for each of them.
It does not enter into subdirectories of git_directory_path
.
GET /api/ruleset-git/files/ Parameters
No parameters.
GET /api/ruleset-git/files/ Responses
Example Response
The response is a JSON object with each key being the name of a file with a .yml
extension in the
git_directory_path
.
Each file entry has an array objects with a commit
ID, commit date
and commit message
.
{
"Ruleset1.yml": [
{"commit": "f061s…46756", "date": "2024-01-10 12:31:45", "message": "Added Column"},
{"commit": "64c18…1a279", "date": "2024-01-09 10:19:13", "message": "Removed Column"}
],
"Another Ruleset.yml": [
{"commit": "377f5…b32f4", "date": "2023-12-25 12:31:45", "message": "Update rule"}
]
}
Response Codes
Status Code | Description |
---|---|
200 |
A JSON serialized list of ruleset names and their associated Git commit history. |
GET /api/ruleset-git/files/ curl
example
curl GET "https://<your-datamasque-host>/api/ruleset-git/files/" \
-H "Authorization: Token <your-api-token>"
POST /api/users/admin-install/
Authorization: Anonymous, Only when no user has been created.
Verify the DataMasque installation, and set up an admin account.
POST /api/users/admin-install/ Parameters
Field | Type | Required | Location | Description |
---|---|---|---|---|
email |
string |
Yes | Request Body | The email of the user you are logging in as. |
username |
string |
Yes | Request Body | The username of the user you are logging in as. |
password |
string |
Yes | Request Body | The password for the user. |
re_password |
string |
Yes | Request Body | The password for the user again, to confirm the password entered above. |
allowed_hosts |
list['string'] |
Yes | Request Body | A list of hostnames that will be allowed to access DataMasque upon installation. |
aws_ec2_instance_id |
string |
No, Only applies to Marketplace installations. | Request Body | The instance id of the AWS EC2. |
POST /api/users/admin-install/ Responses
Status Code | Description |
---|---|
201 |
A JSON serialised User object. |
POST /api/users/admin-install/ curl
example
curl -X POST "https://<your-datamasque-host>/api/users/admin-install/" \
-H "Authorization: Token <your-api-token>" \
-d '{
"email": "<your-admin-email>",
"username": "<your-username>",
"password": "<your-admin-password>",
"re_password": "<your-admin-password>",
"allowed_hosts": ["masque.local"],
"aws_ec2_instance_id": "<your-instance-id>"
}'
Installation Info Object
A JSON object showing the state of the current installation with the following data:
Field | Type | Description |
---|---|---|
is_aws_marketplace |
boolean |
Whether the current installation has been installed from the AWS marketplace. |
installed |
boolean |
If the current installation has been successfully installed. |
is_smtp_configured |
boolean |
If SMTP has been configured on the DataMasque instance. |
is_saml_sso_configured |
boolean |
Is SSO has been enabled on the DataMasque instance. |
- Requests that use Installation Info Object:
GET /api/app/check/
Authorization: User token or API token.
Checks to verify if DataMasque has successfully been installed.
GET /api/app/check/ Parameters
No parameters.
GET /api/app/check/ Response
Code 200
Description:
Status Code | Description |
---|---|
200 |
A JSON serialised Installation Info Object object. |
GET /api/app/check/ curl
example
curl GET "https://<your-datamasque-host>/api/app/check/" \
-H "Authorization: Token <your-api-token>"
POST /api/license-upload/
Authorization: User token only.
Uploads a licence file to DataMasque.
POST /api/license-upload/ Parameters
No parameters.
POST /api/license-upload/ Responses
Status Code | Description |
---|---|
200 |
Operation succeeded. |
POST /api/license-upload/ curl
example
curl -X POST "https://<your-datamasque-host>/api/license-upload/" \
-H "Authorization: Token <your-api-token>" \
-H "Content-Type: application/json" \
-F "license_file=@</path/to/your/license_file.lic>"
Health Check Object
Various health statistics about the DataMasque instance:
Field | Type | Description |
---|---|---|
worker_running |
boolean |
true if the masking agent worker processes are healthy, false if there are no available workers. |
license_expired |
boolean |
true if the licence is expired, false if the licence is not expired. |
license_renewal_in_days |
integer |
Remaining days until licence expiry. |
license_limit_breach |
object |
An object describing any licence breaches that have occurred. Each property on the object is the type of breach that has occurred. Each property value is an object containing breach_type , message , and created_date properties. |
GET /api/health-check/
Authorization: User token or API token.
Get the basic health-check status of DataMasque.
GET /api/health-check/ Parameters
No parameters.
GET /api/health-check/ Responses
Status Code | Description |
---|---|
200 |
A JSON serialised Health Check Object. |
500 |
A server error has occurred, such as an invalid license file exists. The known error will be returned. |
GET /api/health-check/ curl
example
curl GET "https://<your-datamasque-host>/api/health-check/" \
-H "Authorization: Token <your-api-token>"