API Reference

Authentication:
- POST /auth/token/login
User Object:
- GET /users/
- GET /users/me/
Run Object:
- GET /runs/
- POST /runs/
- GET /runs/{id}/
- POST /runs/{id}/cancel/
- GET /runs/{id}/sdd-report/
- Option Object (Referenced in the /runs/ POST Request)
Runlog Object:
- GET /runs/{id}/log/
Connection Object:
Connection Fileset Object:
Ruleset Object:
Seed Object:
- GET /seeds/
- POST /seeds/
Audit Log Object:
- GET /audit-logs/
- GET /audit-logs/download/
Generate ruleset
- POST /generate-ruleset/
Generate Ruleset Result Object
- GET /async-generate-ruleset/{connection_id}
- POST /async-generate-ruleset/{connection_id}
Oracle Wallets:
Other API Requests:

Authentication

The DataMasque API uses token authentication. You can get your token from the 'My Account' screen:

To use the token, include it in the Authorization header within each request, with Token prepended to the token value. For example:

GET /runs/123/
Authorization: Token <your-api-token>
Accept: application/json

Requests related to Authentication:
- POST /auth/token/login

POST /auth/token/login/

POST /auth/token/login/ Parameters

Field	Type	Description
`username`	`string`	The username of the user you are logging in as.
`password`	`string`	The password for the user.

POST /auth/token/login/ Sample Request

POST /auth/token/login/

{
  'username':'connection_name',
  'user':'connection_user'
}

POST /auth/token/login/ Responses

Code: 200

Description:

A JSON serialised user object, including a short-lived API key.

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 /users/me/
- GET /users/

GET /users/

Returns a list of user accounts.

GET /users/ Parameters

None.

GET /users/ Sample Request

GET /api/users/
Authorization: Token <your-api-token>
Content-Type: application/json

GET /users/ Responses

Code: 200

Description:

Returns a JSON serialised list of User objects.

GET /users/ Parameters

None.

GET /users/me/

Returns the details of the currently logged-in user.

GET /users/me Sample Request

GET /api/users/me/
Authorization: Token <your-api-token>
Content-Type: application/json

GET /users/me Responses

Code: 200

Description:

Returns a JSON serialised User object for the user that is currently logged in.

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 /runs/
- POST /runs/
- GET /runs/{id}/
- POST /runs/{id}/cancel/
- GET /runs/{id}/sdd-report/
- Option Object (Referenced in the /runs/ POST Request)

GET /runs/

Get a list DataMasque Runs.

GET /runs/ Parameters

None.

GET /runs/ Sample Request

GET /runs/
Authorization: Token <your-api-token>
Accept: application/json

GET /runs/ Responses

Code: 200

Description:

A JSON serialised list of Run objects.

POST /runs/

Start a new masking run.

POST /runs/ Parameters

Field	Type	Description
`name`	`string`	The name of the `Run`.
`connection`	`string`	Deprecated, replaced by `source_connection`.
`source_connection`	`string`	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`	`Optional[string]`	A UUID identifying the connection to be used for this `Run`. Only required for runs on file connections.
`ruleset`	`string`	A UUID identifying the ruleset to be used for this `Run`.
`options`	`object`	An Option object of configuration for this `Run`.

POST /runs/ Sample Request

POST /api/runs/
Authorization: Token <your-api-token>
Content-Type: application/json

{
    "name": "test_20200430",
    "connection": "9a325a79-af24-4c84-97fe-63246cb0c052",
    "ruleset": "1317030f-f584-49bd-bdb1-a334ae988aba",
    "options": {
        "dry_run": false,
        "max_rows": "1000000",
        "batch_size": "10000"
    }
}

POST /runs/ Responses

Code: 201

Description:

A JSON serialised Run Object.

GET /runs/{id}/

Retrieve information about a masking run.

GET /runs/{id}/ Parameters

Field	Type	Description
`id`	`integer`	The `id` of the `Run`.

GET /runs/{id}/ Sample Request

GET /api/runs/123/
Authorization: Token <your-api-token>
Content-Type: application/json

GET /runs/{id}/ Responses

Code: 200

Description:

A JSON serialised Run object.

POST /runs/{id}/cancel/

Cancel a masking run.

POST /runs/{id}/cancel/ Parameters

Field	Type	Description
`id`	`integer`	The `id` of the `Run`.

POST /runs/{id}/cancel/ Sample Request

POST /api/runs/123/cancel/
Authorization: Token <your-api-token>
Content-Type: application/json

POST /runs/{id}/cancel/ Responses

Code: 201

GET /runs/{id}/sdd-report/

A binary serialised sdd-report object.

GET /runs/{id}/sdd-report/ Parameters

None.

GET /runs/{id}/sdd-report/ Sample Request

GET /api/runs/123/sdd-report/
Authorization: Token <your-api-token>
Content-Type: application/json

GET /runs/{id}/sdd-report/ Responses

Code: 200

Description:

The server will return the sdd-report in the response.content which can be then downloaded as a CSV file.

Code: 404

Description:

If there is no sdd-report for a run, the server will return 404 status code.

Option Object

Option objects have the following fields:

Field	Type	Description
`batch_size`	`integer`	Optional 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`	Optional parameter to specify the maximum number of rows that will be masked by each `mask_table` task¹. 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 ². 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`.

¹max_rows does not apply to mask_unique_key tasks.

²The run_secret contained in the API response can be provided in subsequent API calls to start runs, facilitating consistent masking across those runs.

Requests related to Option Object:
- POST /runs/

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 /runs/{id}/log/

GET /runs/{id}/log/

List all logs for a specified Run.

GET /runs/{id}/log/ Parameters

Field	Type	Description
`id`	`integer`	The `id` of the `Run`.

GET /runs/{id}/log/ Sample Request

GET /api/runs/123/log/
Authorization: Token <your-api-token>
Content-Type: application/json

GET /runs/{id}/log/ Responses

Code: 200

Description:

A JSON serialised list of Runlog objects.

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.
`password`	`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. (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"` or `"azure_blob_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 /connections/

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 /connections/ Parameters

Can optionally follow the URL with the id of a specific connection to only return information on that connection.

GET /connections/ Sample Request

GET /connections/
Authorization: Token <your-api-token>
Accept: application/json

GET /connections/ Responses

Code: 200

Description:

A JSON serialised Connection object.

POST /connections/

Create a new connection object.

POST /connections/ Parameters

For database connections please refer to the following table for fields to create a connection object.

Field	Type	Description
`version`	`string`	The connection version. This should be set to `1.0'.
`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.
`password`	`string`	The password for the user connecting to the database.
`schema`	`string`	The schema of the database to connect to. (Optional)
`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. (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.

For file connections please refer to the following table for fields needed to create a connection object.

Field	Type	Description
`version`	`string`	The connection version. This should be set to `1.0'.
`name`	`string`	The name of the `Connection`.
`type`	`string`	The type of file system the connection is connecting to. Valid options are `"s3_connection"` or `"azure_blob_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.

POST /connections/ Sample Request (Database)

POST /api/connections/
Authorization: Token <your-api-token>
Content-Type: application/json

{
  'version': '1.0',
  'name': 'connection_name',
  'user': 'connection_user',
  'db_type': 'oracle',
  'database': 'database',
  'host': 'host',
  'port': 1433,
  'password': 'password',
  'schema': '',        #optional
  'service_name': '',  #optional
  'connection_fileset': '', #optional
  'mask_type':'database', #optional
  'is_file_mask_source': False, #optional
  'is_file_mask_destination': False #optional
}

POST /connections/ Sample Request (File)

POST /api/connections/
Authorization: Token <your-api-token>
Content-Type: application/json

{
  'version': '1.0',
  'name': 'connection_name',
  'type': 's3_connection',
  'base_directory': '',
  'bucket': 'my_S3_bucket_name',
  'mask_type': 'file',
  'is_file_mask_source': True,
  'is_file_mask_destination': False
}

POST /connections/ Responses

Code: 200

Description:

A JSON serialised Connection object.

PUT /connections/{id}/

Update a connection with a specified id with new values.

PUT /connections/{id}/ Parameters (Database)

Field	Type	Description
`version`	`string`	The connection version. This should be set to `1.0'.
`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.
`password`	`string`	The password for the user connecting to the database.
`schema`	`string`	The schema of the database to connect to. (Optional)
`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. (Optional)
`mask_type`	`string`	The type of masking the connection can perform, only `database` or `file` are valid. (Optional) Defaults to `database` if not provided.

PUT /connections/{id}/ Parameters (File)

Field	Type	Description
`version`	`string`	The connection version. This should be set to `1.0'.
`name`	`string`	The name of the `Connection`.
`type`	`string`	The type of file system the connection is connecting to. Valid options are `"s3_connection"` or `"azure_blob_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) Defaults to `database` if not provided.
`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.

PUT /connections/{id}/ Sample Request

PUT /api/connections/{connection_id}/
Authorization: Token <your-api-token>
Content-Type: application/json

{
  'name': 'connection_name',
  'user': 'new_connection_user',
  'db_type': 'oracle',
  'database': 'new_database',
  'host': 'host',
  'port': 1433,
  'password': 'new_password',
  'schema': '',        #optional
  'service_name': '',  #optional
  'connection_fileset': '' #optional
  'version': '1.0'
}

PUT /connections/{id}/ Responses

Code: 200

Description:

A JSON serialised Connection object with the new updated values.

DELETE /connections/{id}/

Deletes the connection with the specified id.

DELETE /connections/{id}/ Parameters

None.

DELETE /connections/{id}/ Sample Request

DELETE /connections/{id}/
Authorization: Token <your-api-token>
Accept: application/json

DELETE /connections/{id}/ Responses

Code: 204

POST /connections/test

Test a connection to validate that it is able to successfully connect to the target database.

POST /connections/test Parameters

Field	Type	Description
`version`	`string`	The connection version. This should be set to `1.0`.
`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.
`password`	`string`	The password for the user connecting to the database.
`schema`	`string`	The schema of the database to connect to. (Optional)
`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. (Optional)

POST /connections/test Sample Request

POST /api/connections/test
Authorization: Token <your-api-token>
Content-Type: application/json

{
  'name': 'connection_name',
  'user': 'connection_user',
  'db_type': 'oracle',
  'database': 'database',
  'host': 'host',
  'port': 1433,
  'password': 'password',
  'schema': '',        #optional
  'service_name': '',  #optional
  'connection_fileset': '', #optional
  'version': '1.0'
}

POST /connections/test Responses

Code: 204

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).
`zip_archive`	`string`	The location of the zip archive.

Requests related to Connection Fileset:

GET /connection-filesets/

Returns a list of Connection Filesets. These may be used to encrypt MySQL connections.

GET /connection-filesets/ Parameters

None.

GET /connection-filesets/ Sample Request

GET /connection-filesets/
Authorization: Token <your-api-token>
Accept: application/json

GET /connection-filesets/ Responses

Code: 201

Description:

A list of JSON serialised Connection Filesets.

POST /connection-filesets/

Create a new Connection Fileset.

POST /connection-filesets/ Parameters

Field	Type	Description
`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).
`zip_archive`	`string`	The location of the zip archive.

POST /connection-filesets/ Sample Request

POST /connection-filesets/
Authorization: Token <your-api-token>
Accept: application/json

{
  'name': 'connection_fileset_name',
  'database_type': 'database_type',
  'zip_archive': 'zip_archive'
}

POST /connection-filesets/ Responses

Code: 201

Description:

A JSON serialised object of the Connection Fileset that was created.

PUT /connection-filesets/{id}/

Update a Connection Fileset.

PUT /connection-filesets/{id}/ Parameters

Field	Type	Description
`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).
`zip_archive`	`string`	The location of the zip archive.

PUT /connection-filesets/{id}/ Sample Request

PUT /connection-filesets/
Authorization: Token <your-api-token>
Accept: application/json

{
  'name':'connection_fileset_name',
  'database_type':'database_type',
  'zip_archive':'zip_archive'
}

PUT /connection-filesets/{id}/ Responses

Code: 201

Description:

The updated JSON serialised object of the Connection Fileset.

DELETE /connection-filesets/{id}/

Deletes the Connection Fileset with the specified id. You may not delete a Connection Fileset associated to an existing connection.

DELETE /connection-filesets/{id}/ Parameters

None.

DELETE /connection-filesets/{id}/ Sample Request

DELETE /connection-filesets/{id}/
Authorization: Token <your-api-token>
Accept: application/json

DELETE /connection-filesets/{id}/ Responses

Code: 204

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 /rulesets/

Returns a list of all rulesets.

Optionally, you can add an {id} to the end of the request to only return the details of the ruleset with that specific id.

GET /rulesets/ Parameters

None.

GET /rulesets/ Sample Request

GET /rulesets/
Authorization: Token <your-api-token>
Accept: application/json

GET /rulesets/ Responses

Code: 200

Description:

A JSON serialised list of Ruleset objects.

POST /rulesets/

Creates a new ruleset.

POST /rulesets/ Parameters

Field	Type	Description
`name`	`string`	The name of the `Ruleset`.
`config_yaml`	`string`	The YAML contents of the `Ruleset`.
`mask_type`	`string`	The masking type of the `Ruleset`. (Optional) Valid options are `"database"` or `"file"`.

POST /rulesets/ Sample Request

POST /api/rulesets/
Authorization: Token <your-api-token>
Content-Type: application/json

{
    "name": "sdd_run",
    "config_yaml":
      "version: '1.0'
      tasks:
        - type: run_data_discovery",
    "mask_type": "database" #optional
}

POST /rulesets/ Responses

Code: 201

Description:

A JSON serialised Ruleset Object.

PUT /rulesets/{id}/

Update an existing ruleset.

PUT /rulesets/{id}/ Parameters

Field	Type	Description
`name`	`string`	The name of the `Ruleset`.
`config_yaml`	`string`	The YAML contents of the `Ruleset`.
`mask_type`	`string`	The masking type of the `Ruleset`. (Optional) Valid options are `"database"` or `"file"`.

PUT /rulesets/{id}/ Sample Request

PUT /api/rulesets/{id}/
Authorization: Token <your-api-token>
Content-Type: application/json

{
    "name": "new_name",
    "config_yaml":
      version: "1.0"
      tasks:
        - type: run_data_discovery
}

PUT /rulesets/{id}/ Responses

Code: 204

Description:

A JSON serialised Ruleset object with the updated values.

DELETE /rulesets/{id}/

Deletes the ruleset with the specified id.

DELETE /rulesets/{id}/ Parameters

None.

DELETE /rulesets/{id}/ Sample Request

DELETE /rulesets/{id}/
Authorization: Token <your-api-token>
Accept: application/json

DELETE /rulesets/{id}/ Responses

Code: 200

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 /seeds/
- POST /seeds/

GET /seeds/

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 /seeds/ Parameters

None.

GET /seeds/ Sample Request

GET /seeds/
Authorization: Token <your-api-token>
Accept: application/json

GET /seeds/ Responses

Code: 200

Description:

A JSON serialised list of Seed objects.

POST /seeds/

Create a new seed from a csv file.

POST /seeds/ Parameters

Field	Type	Description
`name`	`string`	The name of the csv file.
`description`	`string`	A description of the seed file to displayed on the files menu.
`file`	`object`	A JSON object containing a file name, as well as the contents of the csv file.

POST /seeds/ Sample Request

POST /seeds/
Authorization: Token <your-api-token>
Accept: application/json
files={('seed_file', (csv_contents))}

{'name': 'csv_name', 'description': 'foo'}

POST /seeds/ Responses

Code: 201

Description:

A JSON serialised Seed object.

Audit Log Object

GET /audit-logs/

Retrieve all Audit Logs.

GET /audit-logs/ Parameters

None.

GET /audit-logs/ Sample Request

GET /audit-logs/

GET /audit-logs/ Response

Code 200

Description:

A list of JSON objects containing audit logs, which contain the following fields.

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.

GET /audit-logs/download/

Retrieve all Audit Logs.

GET /audit-logs/download/ Parameters

None.

GET /audit-logs/download/ Sample Request

GET /audit-logs/download/

GET /audit-logs/download/ Response

Code 200

Description:

The server will return the audit logs in the response.content which can be then downloaded as a CSV file. The CSV file will contain 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.

POST /generate-ruleset

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.

POST /generate-ruleset Sample Request

POST /api/generate-ruleset/
Authorization: Token <your-api-token>
Content-Type: application/json

{
  "connection": "2ebd7895-dd73-4609-8cd7-fd6bcfcb2f43",
  "selected_columns": {
    "schema_name": {
      "table_name": [
        "column_name_1",
        "column_name_2",
      ]
    }
  }
}

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:
- GET /async-generate-ruleset/{connection_id}/
- POST /async-generate-ruleset/{connection_id}/

GET /async-generate-ruleset/{connection_id}/

Returns result of generating ruleset progress.

GET /async-generate-ruleset/{connection_id}/ Parameters

Field	Type	Description
`connection_id`	`string`	The `id` of the `Connection`.

GET /async-generate-ruleset/{connection_id}/ Responses

Code: 200

Description: A JSON serialised Generate Ruleset Result Object.

POST /async-generate-ruleset/{connection_id}/

Start generating ruleset for selected columns of a connection.

POST /async-generate-ruleset/{connection_id}/ Parameters

Field	Type	Description
`connection_id`	`string`	The `id` of the `Connection`.

POST /async-generate-ruleset/{connection_id}/ Sample Request

POST /api/async-generate-ruleset/{connection_id}/
Authorization: Token <your-api-token>
Content-Type: application/json

{
  "selected_columns": {
    "schema_name": {
      "table_name": [
        "column_name_1",
        "column_name_2",
      ]
    }
  }
}

GET /oracle-wallets/

Returns a list of Oracle wallets. These are used to connect to encrypted Oracle connections.

GET /oracle-wallets/ Parameters

None.

GET /oracle-wallets/ Sample Request

GET /oracle-wallets/
Authorization: Token <your-api-token>
Accept: application/json

GET /oracle-wallets/ Responses

Code: 201

Description:

A JSON serialised list of Oracle wallets.

POST /oracle-wallets/

Create a new Oracle wallet.

POST /oracle-wallets/ Parameters

None.

POST /oracle-wallets/ Sample Request

POST /oracle-wallets/
Authorization: Token <your-api-token>
Accept: application/json

POST /oracle-wallets/ Responses

Code: 201

Description:

A JSON serialised Oracle wallet object of the wallet created.

DELETE /oracle-wallets/{id}/

Deletes the Oracle wallet with the specified id.

DELETE /oracle-wallets/{id}/ Parameters

None.

DELETE /oracle-wallets/{id}/ Sample Request

DELETE /oracle-wallets/{id}/
Authorization: Token <your-api-token>
Accept: application/json

DELETE /oracle-wallets/{id}/ Responses

Code: 204

POST /users/admin-install/

Verify the DataMasque installation, and set up an admin account.

POST /users/admin-install/ Parameters

Field	Type	Description
`email`	`string`	The email of the user you are logging in as.
`username`	`string`	The username of the user you are logging in as.
`password`	`string`	The password for the user.
`re_password`	`string`	The password for the user again, to confirm the password entered above.
`allowed_hosts`	`list['string']`	A list of hostnames that will be allowed to access DataMasque upon installation.
`aws_ec2_instance_id`	`string`	The instance id of the AWS EC2. Applies only to Marketplace installations.

POST /users/admin-install/ Sample Request

POST /api/users/admin-install/
Authorization: Token <your-api-token>
Accept: application/json

{
  'email': 'admin_email@admin.com',
  'username':'username',
  'password': 'admin_password',
  're_password': 'admin_password',
  'allowed_hosts': ['masque.local',], #add the ip to your instance, needed to make sure host is reachable
  'aws_ec2_instance_id': 'i-##############'
}

POST /users/admin-install/ Responses

Code: 201

Description:

A JSON serialised User object.

GET /app/check/

Checks to verify if DataMasque has successfully been installed.

GET /app/check/ Parameters

None.

GET /app/check/ Sample Request

GET /app/check/

GET /app/check/ Response

Code 200

Description:

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.

POST /license-upload/

Uploads a licence file to DataMasque.

POST /license-upload/ Parameters

None.

POST /license-upload/ Sample Request

POST /license-upload/
files={('license_file', (licence_content))}
Authorization: Token <your-api-token>
Accept: application/json

POST /license-upload/ Responses

Code: 200

GET /health-check/

Get the basic health-check status of DataMasque.

GET /health-check/ Parameters

None.

GET /health-check/ Sample Request

GET /api/health-check/
Authorization: Token <your-api-token>
Content-Type: application/json

GET /health-check/ Responses

Code: 200

Description:

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.

Code: 500

Description:

When there is a server error like licence file is invalid, it would return 500 status code with known error in it.