API Reference

  1. Documentation
  2. API Reference

Exclusive to JackDB Enterprise

This feature is only available in JackDB Enterprise.

Endpoints

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

People

Data Sources

Roles

Permissions

API Information

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.

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"
}

JackDB, Inc.

JackDB is a database technology company. Our platform offers a secure, collaborative environment for your organization's queries and data-driven insights.

If you have any questions about JackDB, or simply want to get in touch, contact us at hello@jackdb.com.

For enterprise sales inquiries, contact our sales team.

Product

Company

Legal

© 2017 JackDB, Inc. All rights reserved.