JackDB: A secure, collaborative data environment

Exclusive to JackDB Enterprise

This feature is only available in JackDB Enterprise.

Endpoints

The JackDB API is organized around the following resources and methods:

Clients

Client must address requests to the hostname for their JackDB server. The same hostname that clients use to connect to the JackDB web interface should be used.

Clients must specifiy a User-Agent header. Requests with a blank User-Agent header will be rejected.

Clients must specify an Accept: application/vnd.jackdb.v2+json header.

HTTPS

All API requests must occur over HTTPS.

Authentication

All API requests must be authenticated. Authentication is done using HTTP Authorization header using Basic authentication.

The username is your API key id suffixed with @api. The password is your API secret.

Endpoint Prefix

For the current version of the API, all endpoints are prefixed with /api/v2.

cURL Examples

Examples are provided using the cURL command-line tool to demonstrate the requests to and responses from the various API endpoints. Parameter values are represented as ${PARAMETER} so that you can control and replace them via environment variables.

The examples below assume the following environment variables have been defined. You'll need to replace them with their equivalents for your JackDB environment.

After creating an API key from the web interface, you can find the same values for your JackDB installation by viewing the details of a newly created API key.

export JACKDB_API_URL="https://jackdb.example.com/api/v2"
export JACKDB_API_KEY_ID="423a2940-a1c5-40db-8c3f-9900641e2b36"
export JACKDB_API_KEY_SECRET="Xcn2DbmQflnDSPLFPXfnVxMS4QKZsCzR"

Responses

All API responses are returned as JSON. Whenever possible, HTTP status codes reflecting the response will be returned. Successful responses will return a 200 status code, rejected requests (including authentication errors) will return 40X status codes, and internal server errors will return 50X status codes.

Error response bodies are of the form:

{
    error: {
        message: <string>
    }
}

Common Field Names & Data Types

The following fields have the same semantic meaning, regardless of the object type to which they refer:

id - string : The unique identifier of an object
createdAt - timestamp : The timestamp when the object was created
updatedAt - timestamp : The timestamp when the object was last updated

The id field will remain constant throughout the life of an object.

Timestamp fields are always represented in ISO-8601 format. Ex: 2014-07-31T18:09:58.637Z

Request Bodies

The following Content-Types are allowed for request bodies:

JSON
- Must have a Content-Type: application/json header.
URL Encoded Form Data
- Must have a Content-Type: application/x-www-form-urlencoded header.

Note: Regardless of the format of the request body, API responses will always be returned as JSON.

Objects

The follow top-level resources and properties are represented in the JackDB API.

Person

A Person object has the following properties:
- id : string - The unique identifier of a person
- username : string - The username of a person
- email : string - The email address of a person

Data Source

A Data Source object has the following properties:
- id : string - The unique identifier of a data source
- alias : string - The unique alias of a data source

Role

A Role object has the following properties:
- id : string - The unique identifier of a role
- name : string - The name of a role

Permission

A Permission object has the following properties:
- id : string - The unique identifier of a permission

API endpoints that refer to an individual object can be referenced by any unique identifier for that object. All objects include a unique id. Additionally, most objects include additional fields that may be unique as well.

To use a non-id field to refer to an object, prefix the field name with a colon (:) in the request path.

Example if a person has an id of P123456789, a username of alice, and an email of alice@example.com, then the following are equivalent and reference the same API endpoint:

/api/v2/person/P123456789
/api/v2/person/username:alice
/api/v2/person/email:alice@example.com

The Person object

List all people
Returns a list of all people.

GET /api/v2/person

Arguments:

This method has no additional arguments.

Response object:

An array of Person objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the person
- name - string : The name of the person
- username - string : The username of the person
- email - string : The email address of the person
- createdAt - timestamp : When the person was created
- isLocked - boolean : Whether the person is locked

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/person"

Example response:

[
  {
    "id": "P0GLBLsmDP7iqto7R",
    "name": "Vaughn Rasmussen",
    "username": "vrasmussen",
    "email": "vaughn.rasmussen@example.com",
    "createdAt": "2014-09-01T21:46:02.539Z"
  },
  {
    "id": "P11TDFUc9rMeFgSyY",
    "name": "Emmy Armstrong",
    "username": "earmstrong",
    "email": "emmy.armstrong@example.com",
    "createdAt": "2014-08-27T01:11:36.077Z"
  },
  {
    "id": "P2227D20azrJ62nYE",
    "name": "Aurora Douglas",
    "username": "adouglas",
    "email": "aurora.douglas@example.com",
    "createdAt": "2014-09-03T06:14:34.593Z"
  }
]

List all data sources accessible to a person
Returns a list of all data sources accessible to a person.

GET /api/v2/person/:person/data-source

Arguments:

person - The identifier of the person whose data sources will be retrieved

Response object:

An array of Data Source objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the data source
- name - string : The name of the data source
- alias - string : The alias of the data source

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/person/P0GLBLsmDP7iqto7R/data-source"

Example response:

[
  {
    "id": "DvZqlrLUHTE4G11L9",
    "name": "GL Production",
    "alias": "gl-prod"
  },
  {
    "id": "DFtlu8gfkiOSl0zf",
    "name": "GL Testing",
    "alias": "gl-uat"
  }
]

List all roles assigned to a person
Returns a list of all roles assigned to a person.

GET /api/v2/person/:person/role

Arguments:

person - The identifier of the person whose roles will be retrieved

Response object:

An array of Role objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the role
- name - string : The name of the role
- assignedAt - timestamp : When the person was assigned to the role

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/person/P0GLBLsmDP7iqto7R/role"

Example response:

[
  {
    "id": "RHZ7pTXMCm3HrhG92",
    "name": "Finance",
    "assignedAt": "2014-09-04T16:20:09.138Z"
  },
  {
    "id": "RPJa0nipdJrG9kl6z",
    "name": "HR",
    "assignedAt": "2014-09-03T17:13:49.955Z"
  }
]

List all permissions granted to a person
Returns a list of all permissions granted to a person.

GET /api/v2/person/:person/permission

Arguments:

person - The identifier of the person whose permissions will be retrieved

Response object:

An array of Permission objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the permission
- personId - string : The unique identifier of the person granted this permission
- dataSourceId - string : The unique identifier of the data source for this permission
- expiresAt - timestamp : When the permission is set to expire

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/person/P0GLBLsmDP7iqto7R/permission"

Example response:

[
  {
    "id": "68939",
    "personId": "P0cKFCMIHoNaBFt7Y",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "expiresAt": "2015-03-13T00:47:14.120Z"
  },
  {
    "id": "69303",
    "personId": "P0cKFCMIHoNaBFt7Y",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "expiresAt": "2015-03-13T00:47:15.193Z"
  }
]

Delete all permissions granted to a person
Permanently deletes all permissions granted to a person.

DELETE /api/v2/person/:person/permission

Arguments:

person - The identifier of the person whose permissions will be revoked

Response object:

An object with the following properties:
- count - integer : the number of deleted permissions

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/person/P0cKFCMIHoNaBFt7Y/permission"

Example response:

{
  "count": 2
}

Create a person
Creates a new person.

POST /api/v2/person

Arguments:

name : string : The name of the new person
email : string : The email address of the new person
username : string : The username of the new person

Response object:

A newly-created Person object with the following properties:
- id - string : The identifier of the person
- name - string : The name of the person
- email - string : The email address of the person
- username - string : The username of the person
- createdAt - timestamp : When the person was created
- isLocked - boolean : Whether the person is locked

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    "${JACKDB_API_URL}/person" \
    -d "name=Alice%20Smith&email=alice@example.org&username=alice"

Example response:

{
  "id": "PCukhIFFiNQaN19c",
  "name": "Alice Smith",
  "email": "alice@example.org",
  "username": "alice",
  "createdAt": "2015-03-22T16:35:27.376Z"
}

Retrieve a person
Retrieves the details of an existing person.

GET /api/v2/person/:person

Arguments:

person - The identifier of the person to be retrieved

Response object:

A Person object with the following properties:
- id - string : The identifier of the person
- name - string : The name of the person
- username - string : The username of the person
- email - string : The email address of the person
- createdAt - timestamp : When the person was created
- isLocked - boolean : Whether the person is locked

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/person/P0GLBLsmDP7iqto7R"

Example response:

{
  "id": "P0GLBLsmDP7iqto7R",
  "name": "Vaughn Rasmussen",
  "username": "vrasmussen",
  "email": "vaughn.rasmussen@example.com",
  "createdAt": "2014-09-01T21:46:02.539Z"
}

Lock a person
Locks a person.

PUT /api/v2/person/:person/lock

Arguments:

person - The identifier of the person to be locked

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X PUT \
    "${JACKDB_API_URL}/person/P0GLBLsmDP7iqto7R/lock"

Example response:

{}

Note: This is an idempotent endpoint. Locking a person whose account is already locked will return a success response.

Unlock a person
Unlocks a person.

PUT /api/v2/person/:person/unlock

Arguments:

person - The identifier of the person to be unlocked

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X PUT \
    "${JACKDB_API_URL}/person/P0GLBLsmDP7iqto7R/unlock"

Example response:

{}

Note: This is an idempotent endpoint. Unlocking a person whose account is already unlocked will return a success response.

Disable two-factor authentication (2FA)
Disables a person's two-factor authentication (2FA).

DELETE /api/v2/person/:person/two-factor

Arguments:

person - The identifier of the person whose 2FA is to be disabled

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/person/P0GLBLsmDP7iqto7R/two-factor"

Example response:

{}

Note: This is an idempotent endpoint. Disabling two-factor authentication when it is already disabled will return a success response.

The Data Source object

List all data sources
Returns a list of all data sources.

GET /api/v2/data-source

Arguments:

This method has no additional arguments.

Response object:

An array of Data Source objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the data source
- name - string : The name of the data source
- alias - string : The unique alias of the data source
- type - string : The data source type
- configUri - string : The connection URI of the data source
- createdAt - timestamp : When the data source was created
- updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source"

Example response:

[
  {
    "id": "DUGC6IqGQ4DX00Lt0",
    "name": "General Ledger",
    "alias": "gl-prod",
    "type": "postgresql",
    "configUri": "postgresql://gl@db.example.com:5432/gl",
    "createdAt": "2014-08-05T22:05:15.987Z",
    "updatedAt": "2014-09-04T18:23:32.777Z"
  },
  {
    "id": "DBnkfabo6VtpTaI7f",
    "name": "Stuff - Read Only",
    "alias": null,
    "type": "mysql",
    "configUri": "mysql://read_only@mydb.example.com:3306/stuff",
    "createdAt": "2014-08-29T19:55:42.666Z",
    "updatedAt": "2014-09-04T18:23:32.777Z"
  }
]

Note: The connection URI returned by this endpoint does not contain the password of the underlying database; only the database user, hostname, and port number are included.

List all roles containing a data source
Returns a list of all roles containing a data source.

GET /api/v2/data-source/:data-source/role

Arguments:

data-source - The identifier of the data source

Response object:

An array of Role objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the role
- name - string : The name of the role
- assignedAt - timestamp : When the data source was assigned to the role

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/role"

Example response:

[
  {
    "id": "RKm2x3dfX0b505iHy",
    "name": "HR",
    "assignedAt": "2014-07-27T15:01:59.901Z",
  },
  {
    "id": "RC98On0Dus9ZrskYH",
    "name": "Finance",
    "assignedAt": "2014-07-31T18:09:58.637Z",
  }
]

List all permissions granted on a data source
Returns a list of all permissions granted on a data source.

GET /api/v2/data-source/:data-source/permission

Arguments:

data-source - The identifier of the data source

Response object:

An array of Permission objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the permission
- personId - string : The unique identifier of the person to whom this permission is granted
- dataSourceId - string : The unique identifier of the data source onto which this permission is granted
- startsAt - timestamp : When this permission is set to start
- expiresAt - timestamp : When this permission is set to expire

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/permission"

Example response:

[
  {
    "id": "68939",
    "personId": "P0cKFCMIHoNaBFt7Y",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "startsAt": "2015-03-12T23:47:14.120Z",
    "expiresAt": "2015-03-13T00:47:14.120Z"
  },
  {
    "id": "69303",
    "personId": "P0cKFCMIHoNaBFt7Y",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "startsAt": "2015-03-12T23:47:14.120Z",
    "expiresAt": "2015-03-13T00:47:15.193Z"
  },
  {
    "id": "69603",
    "personId": "P3Fz69ORRudnQo5LE",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "startsAt": "2015-03-12T23:47:14.120Z",
    "expiresAt": "2015-03-13T00:47:15.832Z"
  }
]

Delete all permissions granted on a data source
Permanently deletes all permissions granted on a data source.

DELETE /api/v2/data-source/:data-source/permission

Arguments:

data-source - The identifier of the data source

Response object:

An object with the following properties:
- count - integer : the number of deleted permissions

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/permission"

Example response:

{
  "count": 3
}

Create a data source
Creates a new data source.

POST /api/v2/data-source

Arguments:

name - string : The name of the new data source
alias - string : The alias of the new data source (optional)
configUri - string : The connection URI of the data source

Response object:

A newly-created Data Source object with the following properties:
- id - string : The unique identifier of the data source
- name - string : The name of the data source
- alias - string : The unique alias of the data source
- type - string : The data source type
- configUri - string : The connection URI of the data source
- createdAt - timestamp : When the data source was created
- updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    "${JACKDB_API_URL}/data-source" \
    -d name=SomeDB&alias=some-db&configUri=postgresql://someuser:t0ps3cret@somedb.example.com:5432/some-db"

Example response:

{
  "id": "DKgU62P1dUlJfGTG",
  "name": "SomeDB",
  "alias": "some-db",
  "type": "postgresql",
  "configUri": "postgresql://someuser:t0ps3cret@somedb.example.com:5432/some-db?validateSsl=false&ssl=true",
  "createdAt": "2015-03-12T20:25:00.760Z",
  "updatedAt": "2015-03-12T20:25:00.760Z"
}

Retrieve a data source
Retrieves the basic details of an existing data source.

GET /api/v2/data-source/:data-source

Arguments:

data-source - The identifier of the data source to be retrieved

Response object:

A Data Source object with the following properties:
- id - string : The unique identifier of the data source
- name - string : The name of the data source
- alias - string : The unique alias of the data source
- type - string : The data source type
- configUri - string : The connection URI of the data source
- createdAt - timestamp : When the data source was created
- updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0"

Example response:

{
  "id": "DUGC6IqGQ4DX00Lt0",
  "name": "General Ledger",
  "alias": "gl-prod",
  "type": "postgresql",
  "configUri": "postgresql://gl@db.example.com:5432/gl",
  "createdAt": "2014-08-05T22:05:15.987Z",
  "updatedAt": "2014-09-04T18:23:32.777Z"
}

Note: The connection URI returned by this endpoint does not contain the password of the underlying database; only the database user, hostname, and port number are included.

Retrieve a data source (detailed)
Retrieves the details of an existing data source.

GET /api/v2/data-source/:data-source/detail

Arguments:

data-source - The identifier of the data source to be retrieved

Response object:

A Data Source object with the following properties:
- id - string : The unique identifier of the data source
- name - string : The name of the data source
- alias - string : The unique alias of the data source
- type - string : The data source type
- configUri - string : The connection URI of the data source
- createdAt - timestamp : When the data source was created
- updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/detail"

Example response:

{
  "id": "DUGC6IqGQ4DX00Lt0",
  "name": "General Ledger",
  "alias": "gl-prod",
  "type": "postgresql",
  "configUri": "postgresql://gl:t0ps3cret@db.example.com:5432/gl",
  "createdAt": "2014-08-05T22:05:15.987Z",
  "updatedAt": "2014-09-04T18:23:32.777Z"
}

Note: The connection URI returned by this endpoint contains the password of the underlying database.

Update a data source
Updates an existing data source.

POST /api/v2/data-source/:data-source

Arguments:

data-source - The identifier of the data source to be updated
name - string : The name of the data source
alias - string : The alias of the data source
configUri - string : The connection URI of the data source

Response object:

An updated Data Source object with the following properties:
- id - string : The unique identifier of the data source
- name - string : The name of the data source
- alias - string : The unique alias of the data source
- type - string : The data source type
- configUri - string : The connection URI of the data source
- createdAt - timestamp : When the data source was created
- updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    "${JACKDB_API_URL}/data-source/DKgU62P1dUlJfGTG" \
    -d name=SomeDB&alias=some-db&configUri=postgresql://someuser:t0ps3cret@somedb.example.com:5432/some-db"

Example response:

{
  "id": "DKgU62P1dUlJfGTG",
  "name": "SomeDB",
  "alias": "some-db",
  "type": "postgresql",
  "configUri": "postgresql://someuser:t0ps3cret@somedb.example.com:5432/some-db?validateSsl=false&ssl=true",
  "createdAt": "2015-03-12T20:25:00.760Z",
  "updatedAt": "2015-03-12T20:25:00.760Z"
}

Delete a data source
Permanently deletes an existing data source.

DELETE /api/v2/data-source/:data-source

Arguments:

data-source - The identifier of the data source to be deleted

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0"

Example response:

{}

Test a data source
Test connecting to an existing data source.

POST /api/v2/data-source/:data-source/test

Arguments:

data-source - The identifier of the data source to be deleted

Response object:

If the connection attempt is successful, the endpoint returns an object with the following properties:
- success - boolean : Whether a connection to the data source could be established. (will be true for success responses)
- version - object : The server version of the data source. This is provided for informational purposes and the exact format of this object may change in a future release. Currently it returns the major/minor/patch version of the remote database server as well as a text description of the server software and version.
If the connection attempt is not successful, the endpoint returns an object with the following properties:
- success - boolean : Whether a connection to the data source could be established. (will be false for unsuccessful responses)
- message - string : A description of the error encountered connecting to the data source.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/test"

Example responses:

{
  "success": true,
  "version": {
    "productName": "PostgreSQL",
    "productVersion": "9.6.2",
    "major": 9,
    "minor": 6,
    "patch": 2
  }
}

{
  "success": false,
  "message": "The connection timed out while trying to establish a connection. Please check that your data source is online and the proper firewall configuration has been setup."
}

The Role object

List all roles
Returns a list of all roles.

GET /api/v2/role

Arguments:

This method has no additional arguments.

Response object:

An array of Role objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the role
- name - string : The name of the role
- createdAt - timestamp : When the role was created
- updatedAt - timestamp : When the role was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/role"

Example response:

[
  {
    "updatedAt": "2014-07-31T18:09:58.637Z",
    "createdAt": "2014-07-27T15:01:59.901Z",
    "name": "HR",
    "id": "RKm2x3dfX0b505iHy"
  },
  {
    "updatedAt": "2014-07-31T18:09:58.637Z",
    "createdAt": "2014-07-20T17:02:16.387Z",
    "name": "Finance",
    "id": "RC98On0Dus9ZrskYH"
  },
  {
    "updatedAt": "2014-07-31T18:09:58.637Z",
    "createdAt": "2014-07-12T12:04:28.334Z",
    "name": "CRM",
    "id": "RjNMsZ80ELfcxDSv1"
  }
]

List all data sources in a role
Returns a list of all data sources in a role.

GET /api/v2/role/:role/data-source

Arguments:

role - The identifier of a role

Response object:

An array of Data Source objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the data source
- name - string : The name of the data source
- alias - string : The unique alias of the data source
- assignedAt - timestamp : When the data source was added to the role

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/role/RKm2x3dfX0b505iHy/data-source"

Example response:

[
  {
    "id": "DvZqlrLUHTE4G11L9",
    "name": "GL Production",
    "alias": "gl-prod",
    "assignedAt": "2015-03-05T17:02:35.314Z"
  },
  {
    "id": "DFtlu8gfkiOSl0zf",
    "name": "GL Testing",
    "alias": "gl-uat",
    "assignedAt": "2015-02-15T20:07:12.501Z"
  }
]

List all people assigned to a role
Returns a list of all people assigned to a role.

GET /api/v2/role/:role/person

Arguments:

role - The identifier of a role

Response object:

An array of Person objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the person
- username - string : The username of the person
- email - string : The email address of the person
- name - string : The name of the person
- assignedAt - timestamp : When the person was assigned to the role

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/role/RKm2x3dfX0b505iHy/person"

Example response:

[
  {
    "id": "P0cKFCMIHoNaBFt7Y",
    "username": "ghiggins",
    "email": "griffin.higgins@example.com",
    "name": "Griffin Higgins",
    "assignedAt": "2014-07-28T01:21:56.147Z"        
  },
  {
    "id": "P3Fz69ORRudnQo5LE",
    "username": "astark",
    "email": "ameer.stark@example.com",
    "name": "Ameer Stark",
    "assignedAt": "2014-07-31T01:25:19.874Z"
  },
  {
    "id": "P9mbZ6vLpPJETzAW2",
    "username": "abuckner",
    "email": "alexia.buckner@example.com",
    "name": "Alexia Buckner",
    "assignedAt": "2014-07-29T13:35:40.433Z"
  }
]

Add a data source to a role
Adds a data source to a role.

PUT /api/v2/role/:role/data-source/:data-source

Arguments:

role - The identifier of a role
data-source - The identifier of a data source to add to the role

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X PUT \
    "${JACKDB_API_URL}/role/RKm2x3dfX0b505iHy/data-source/DvZqlrLUHTE4G11L9"

Example response:

{}

Note: This is an idempotent endpoint. Adding a data source to a role that already contains the data source will return a success response.

Assign a person to a role
Assign a person to a role.

PUT /api/v2/role/:role/person/:person

Arguments:

role - The identifier of a role
person - The identifier of a person to assign to the role

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X PUT \
    "${JACKDB_API_URL}/role/RKm2x3dfX0b505iHy/person/P9mbZ6vLpPJETzAW2"

Example response:

{}

Note: This is an idempotent endpoint.

Remove a data source from a role
Permanently removes a data source from a role.

DELETE /api/v2/role/:role/data-source/:data-source

Arguments:

role - The identifier of a role
data-source - The identifier of a data source to remove from the role

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/role/RKm2x3dfX0b505iHy/data-source/DvZqlrLUHTE4G11L9"

Example response:

{}

Remove a person from a role
Permanently removes a person from a role.

DELETE /api/v2/role/:role/person/:person

Arguments:

role - The identifier of a role
person - The identifier of a person to remove from the role

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/role/RKm2x3dfX0b505iHy/person/P9mbZ6vLpPJETzAW2"

Example response:

{}

Create a role
Creates a new role.

POST /api/v2/role

Arguments:

name : string : The name of the new role

Response object:

A newly-created Role object with the following properties:
- id - string : The unique identifier of the role
- name - string : The name of the role
- createdAt - timestamp : When the role was created
- updatedAt - timestamp : When the role was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    "${JACKDB_API_URL}/role" \
    -d "name=SomeRole"

Example response:

{
  "updatedAt": "2015-03-12T15:07:00.966Z",
  "createdAt": "2015-03-12T15:07:00.966Z",
  "name": "SomeRole",
  "id": "Rhq4aWOpNa6grdh6"
}

Retrieve a role
Retrieves the details of an existing role.

GET /api/v2/role/:role

Arguments:

role - The identifier of the role to be retrieved

Response object:

A Role object with the following properties:
- id - string : The unique identifier of the role
- name - string : The name of the role
- createdAt - timestamp : When the role was created
- updatedAt - timestamp : When the role was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/role/RKm2x3dfX0b505iHy"

Example response:

{
  "id": "RKm2x3dfX0b505iHy",
  "name": "HR",
  "createdAt": "2014-07-27T15:01:59.901Z",
  "updatedAt": "2014-07-31T18:09:58.637Z"
}

Delete a role
Permanently deletes an existing role.

DELETE /api/v2/role/:role

Arguments:

role - The identifier of the role to be deleted

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/role/Rhq4aWOpNa6grdh6"

Example response:

{}

The Permission object

List all permissions
Returns a list of all permissions.

GET /api/v2/permission

Arguments:

This method has no additional arguments.

Response object:

An array of Permission objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the permission
- createdAt - timestamp - When this permission was created
- startsAt - timestamp : When this permission is set to start
- expiresAt - timestamp : When this permission is set to expire
- person - object : The Person object to whom this permission is granted
  - id - string : The unique identifier of the person
  - name - string : The name of the person
  - username - string : The username of the person
  - email - string : The email address of the person
- dataSource - object : The Data Source object onto which this permission is granted
  - id - string : The unique identifier of the data source
  - name - string : The name of the data source
  - alias - string : The alias of the data source

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/permission"

Example response:

[
  {
    "id": "19213",
    "createdAt": "2015-03-13T13:57:07.858Z",
    "startsAt": "2015-03-13T13:57:07.858Z",
    "expiresAt": "2015-03-13T15:03:47.858Z",
    "person": {
      "id": "P7ueWXlRjejZU3Yzt",
      "name": "Alexia Buckner",
      "username": "abuckner",
      "email": "alexia.buckner@example.com"
    },
    "dataSource": {
      "id": "DUGC6IqGQ4DX00Lt0",
      "name": "General Ledger",
      "alias": "gl-prod"
    }
  },
  {
    "id": "19218",
    "createdAt": "2015-03-13T13:57:28.216Z",
    "expiresAt": "2015-03-14T13:57:28.216Z",
    "person": {
      "id": "PTbjsa5vR6Hu5aIT5",
      "name": "Zayne Tran",
      "username": "ztran",
      "email": "zayne.tran@example.com"
    },
    "dataSource": {
      "id": "DUGC6IqGQ4DX00Lt0",
      "name": "General Ledger",
      "alias": "gl-prod",
    }
  }
]

List all permissions (specific)
Returns a list of all permissions granting access to a data source to a specific person.

GET /api/v2/data-source/:data-source/permission/person/:person

Arguments:

data-source - The identifier of a data source
person - The identifier of a person

Response object:

An array of Permission objects
Each entry in the array is an object with the following properties:
- id - string : The unique identifier of the permission
- personId - string : The unique identifier of the person
- dataSourceId - string : The unique identifier of the data source
- startsAt - timestamp : When the permission is set to start
- expiresAt - timestamp : When the permission is set to expire

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/permission/person/P0cKFCMIHoNaBFt7Y"

Example response:

[
  {
    "id": "68939",
    "personId": "P0cKFCMIHoNaBFt7Y",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "startsAt": "2015-03-12T23:47:14.120Z",
    "expiresAt": "2015-03-13T00:47:14.120Z"
  },
  {
    "id": "69303",
    "personId": "P0cKFCMIHoNaBFt7Y",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "startsAt": "2015-03-12T23:47:14.120Z",
    "expiresAt": "2015-03-13T00:47:15.193Z"
  }
]

Delete all permissions (specific)
Permanently deletes all permissions associated with a specific person and data source.

DELETE /api/v2/data-source/:data-source/permission/person/:person

Arguments:

data-source - The identifier of a data source
person - The identifier of a person

Response object:

An object with the following properties:
- count - integer : the number of deleted permissions

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/permission/person/P0cKFCMIHoNaBFt7Y"

Example response:

{
  "count": 2
}

Create a permission
Creates a permission granting access to a data source to a specific person.

POST /api/v2/data-source/:data-source/permission/person/:person

Arguments:

data-source - The identifier of a data source
person - The identifier of a person
duration - integer : The number of seconds the permission will be active
startsAt - timestamp : An optional, deferred time for the permission to start; otherwise, the permission will start immediately

Response object:

A newly-created Permission object with the following properties:
- id - string : The unique identifier of the permission
- startsAt - timestamp : When the permission is set to start
- expiresAt - timestamp : When the permission is set to expire
- createdAt - timestamp : When the permission was created

Example request (starting immediately):

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    -d "duration=86400" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/permission/person/P0cKFCMIHoNaBFt7Y"

Example response:

{
  "id": "13382",
  "startsAt": "2015-03-12T22:17:29.609Z"
  "expiresAt": "2015-03-13T22:17:29.609Z",
  "createdAt": "2015-03-12T22:17:29.609Z"
}

Example request (deferred):

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    -d "duration=86400&startsAt=2015-03-23T23:00:00.000Z" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/permission/person/P0cKFCMIHoNaBFt7Y"

Example response:

{
  "id": "23385",
  "startsAt": "2015-03-23T23:00:00.000Z"
  "expiresAt": "2015-03-24T23:00:00.000Z",
  "createdAt": "2015-03-21T22:17:29.609Z"
}

Retrieve a permission
Retrieves the details of an existing permission.

GET /api/v2/permission/:permission

Arguments:

permission - The identifier of the permission to be retrieved

Response object:

A Permission object with the following properties:
- id - string : The unique identifier of the permission
- createdAt - timestamp - When this permission was created
- expiresAt - timestamp : When this permission is set to expire
- person - object : The Person object to whom this permission is granted
  - id - string : The unique identifier of the person
  - name - string : The name of the person
  - username - string : The username of the person
  - email - string : The email address of the person
- dataSource - object : The Data Source object onto which this permission is granted
  - id - string : The unique identifier of the data source
  - name - string : The name of the data source
  - alias - string : The alias of the data source

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/permission/19213"

Example response:

{
  "id": "19213",
  "createdAt": "2015-03-13T13:57:07.858Z",
  "expiresAt": "2015-03-13T15:03:47.858Z",
  "person": {
    "id": "P7ueWXlRjejZU3Yzt",
    "name": "Alexia Buckner",
    "username": "abuckner",
    "email": "alexia.buckner@example.com"
  },
  "dataSource": {
    "id": "DUGC6IqGQ4DX00Lt0",
    "name": "General Ledger",
    "alias": "gl-prod"
  }
}

Delete a permission
Permanently deletes an existing permission.

DELETE /api/v2/permission/:permission

Arguments:

permission - The identifier of the permission to be deleted

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/permission/19213"

Example response:

{}

API Information

Who Am I
Returns information based on the current API key.

GET /api/v2/whoami

Arguments:

This method has no additional arguments.

Response object:

An object with the following properties:
- id - string : The unique identifier of the current API key
- name - string : The name of the API key
- type - string : The authentication type, e.g., "token" for API requests

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/whoami"

Example response:

{
    "id": "423a2940-a1c5-40db-8c3f-9900641e2b36",
    "name": "My API Key",
    "type": "token"
}

API Reference

Exclusive to JackDB Enterprise

Endpoints

People

Data Sources

Roles

Permissions

API Information

Clients

HTTPS

Authentication

Endpoint Prefix

cURL Examples

Responses

Common Field Names & Data Types

Request Bodies

Objects

Person

Data Source

Role

Permission

The Person object

List all people

List all data sources accessible to a person

List all roles assigned to a person

List all permissions granted to a person

Delete all permissions granted to a person

Create a person

Retrieve a person

Lock a person

Unlock a person

Disable two-factor authentication (2FA)

The Data Source object

List all data sources

List all roles containing a data source

List all permissions granted on a data source

Delete all permissions granted on a data source

Create a data source

Retrieve a data source

Retrieve a data source (detailed)

Update a data source

Delete a data source

Test a data source

The Role object

List all roles

List all data sources in a role

List all people assigned to a role

Add a data source to a role

Assign a person to a role

Remove a data source from a role

Remove a person from a role

Create a role

Retrieve a role

Delete a role

The Permission object

List all permissions

List all permissions (specific)

Delete all permissions (specific)

Create a permission

Retrieve a permission

Delete a permission

API Information

Who Am I

JackDB, Inc.

Product

Company

Legal