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
- 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 a person's two-factor authentication (2FA)
Data Sources
- 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
Roles
- 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
Permissions
- List all permissions
- List all permissions (specific)
- Delete all permissions (specific)
- Create a permission
- Retrieve a permission
- Delete a permission
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 objectcreatedAt
- timestamp : The timestamp when the object was createdupdatedAt
- 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-Type
s are allowed for request bodies:
- JSON
- Must have a
Content-Type: application/json
header.
- Must have a
- URL Encoded Form Data
- Must have a
Content-Type: application/x-www-form-urlencoded
header.
- Must have a
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 personusername
: string - The username of a personemail
: 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 sourcealias
: string - The unique alias of a data source
Role
- A Role object has the following properties:
id
: string - The unique identifier of a rolename
: 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 personname
- string : The name of the personusername
- string : The username of the personemail
- string : The email address of the personcreatedAt
- timestamp : When the person was createdisLocked
- 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 sourcename
- string : The name of the data sourcealias
- 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 rolename
- string : The name of the roleassignedAt
- 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 permissionpersonId
- string : The unique identifier of the person granted this permissiondataSourceId
- string : The unique identifier of the data source for this permissionexpiresAt
- 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 personemail
: string : The email address of the new personusername
: string : The username of the new person
Response object:
- A newly-created Person object with the following properties:
id
- string : The identifier of the personname
- string : The name of the personemail
- string : The email address of the personusername
- string : The username of the personcreatedAt
- timestamp : When the person was createdisLocked
- 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 personname
- string : The name of the personusername
- string : The username of the personemail
- string : The email address of the personcreatedAt
- timestamp : When the person was createdisLocked
- 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 sourcename
- string : The name of the data sourcealias
- string : The unique alias of the data sourcetype
- string : The data source typeconfigUri
- string : The connection URI of the data sourcecreatedAt
- timestamp : When the data source was createdupdatedAt
- 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 rolename
- string : The name of the roleassignedAt
- 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 permissionpersonId
- string : The unique identifier of the person to whom this permission is granteddataSourceId
- string : The unique identifier of the data source onto which this permission is grantedstartsAt
- timestamp : When this permission is set to startexpiresAt
- 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 sourcealias
- 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 sourcename
- string : The name of the data sourcealias
- string : The unique alias of the data sourcetype
- string : The data source typeconfigUri
- string : The connection URI of the data sourcecreatedAt
- timestamp : When the data source was createdupdatedAt
- 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 sourcename
- string : The name of the data sourcealias
- string : The unique alias of the data sourcetype
- string : The data source typeconfigUri
- string : The connection URI of the data sourcecreatedAt
- timestamp : When the data source was createdupdatedAt
- 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 sourcename
- string : The name of the data sourcealias
- string : The unique alias of the data sourcetype
- string : The data source typeconfigUri
- string : The connection URI of the data sourcecreatedAt
- timestamp : When the data source was createdupdatedAt
- 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 sourcename
- string : The name of the data sourcealias
- string : The unique alias of the data sourcetype
- string : The data source typeconfigUri
- string : The connection URI of the data sourcecreatedAt
- timestamp : When the data source was createdupdatedAt
- 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 rolename
- string : The name of the rolecreatedAt
- timestamp : When the role was createdupdatedAt
- 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 sourcename
- string : The name of the data sourcealias
- string : The unique alias of the data sourceassignedAt
- 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 personusername
- string : The username of the personemail
- string : The email address of the personname
- string : The name of the personassignedAt
- 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 rolename
- string : The name of the rolecreatedAt
- timestamp : When the role was createdupdatedAt
- 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 rolename
- string : The name of the rolecreatedAt
- timestamp : When the role was createdupdatedAt
- 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 permissioncreatedAt
- timestamp - When this permission was createdstartsAt
- timestamp : When this permission is set to startexpiresAt
- timestamp : When this permission is set to expireperson
- object : The Person object to whom this permission is grantedid
- string : The unique identifier of the personname
- string : The name of the personusername
- string : The username of the personemail
- string : The email address of the person
dataSource
- object : The Data Source object onto which this permission is grantedid
- string : The unique identifier of the data sourcename
- string : The name of the data sourcealias
- 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 permissionpersonId
- string : The unique identifier of the persondataSourceId
- string : The unique identifier of the data sourcestartsAt
- timestamp : When the permission is set to startexpiresAt
- 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 permissionstartsAt
- timestamp : When the permission is set to startexpiresAt
- timestamp : When the permission is set to expirecreatedAt
- 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 permissioncreatedAt
- timestamp - When this permission was createdexpiresAt
- timestamp : When this permission is set to expireperson
- object : The Person object to whom this permission is grantedid
- string : The unique identifier of the personname
- string : The name of the personusername
- string : The username of the personemail
- string : The email address of the person
dataSource
- object : The Data Source object onto which this permission is grantedid
- string : The unique identifier of the data sourcename
- string : The name of the data sourcealias
- 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 keyname
- string : The name of the API keytype
- 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"
}