REST API

The REST API is a powerful tool that allows external communications with the BizDock data.

Security management

Concepts

API action

An API action represents simply a method of the API, for example “get the actors” or “create a portfolio entry”.

Authentication headers

When calling the API, the HTTP request should contains some headers used for the authentication:

  • X-bizdock-timestamp: The current timestamp in milliseconds
  • X-bizdock-application: The application key
  • X-bizdock-signature: The request signature

API authentication mode

The API authentication mode defines the way to secure the communication with the API. There are 2 modes:

  • APPLICATION_KEY_ONLY: each request should include an application key in the header in order to authenticate the sender.
  • SIGNATURE: each request should include an signature in the header and should be signed with a secret key. This allows to authenticate the sender and prevent also man-in-the-middle attack.

The API could be only called with a secured communication protocol (HTTPS), so the requests and responses (including the headers) are in both cases encrypted.

API key

An API key is a pair of keys (application and secret) that are used to create a request. An API key also contains a configuration to define which actions are authorized.

Change the API authentication mode

→ To change the API authentication mode, the permission ADMIN_CONFIGURATION_PERMISSION is required.

  1. Go to the System preferences,
  2. Click on “Update”,
  3. Under “API authenticaton mode”, select the wished mode.

API keys management

→ To manage the API keys, the permission API_MANAGER_PERMISSION is required.

The API keys management interface is available from the “Integration” item inside the “Admin” menu. Then select the “API keys” item from the left menu.

Attributes

Field Description
Is testable A testable key could be used in the API browser.
Name The name of the key.
Description The description of the key.
API authorizations List of authorized actions for the key. An authorization is defined by an HTTP method and a pattern for the actions, it follows this syntax: {HTTP_METHOD} {ACTIONS_PATTERN}.
HTTP_METHOD: could be GET, POST, PUT or DELETE.
ACTIONS_PATTERN: a regular expression which described the authorized actions according to their routes.
Examples:
GET /api/core/portfolio/.* : All GET actions that start with /api/core/portfolio/
POST (.*) : all POST actions
Secret key The secret key used to sign the requests (automatically generated).
Application key The application key used to authenticate the request sender (automatically generated).
Protocol version The protocol version, currently 1 (automatically generated).
Hash algorithm The hash algorithm for the signature, currently SHA-512 (automatically generated).

Create an API key

  1. Go to the “API configuration manager”,
  2. Click on the “Add” icon inside the Registered applications table,
  3. Complete the API key's attributes and Save,
  4. The new API key is created with an application and a secret keys auto-generated.

Edit an API key

  1. Go to the “API configuration manager”,
  2. Click on the “Edit” icon for the wished API key,
  3. Modify the API key's attributes and Save,
  4. The API key data have been updated.

The application and secret keys are not modified.

Reset an API key

It is possible to reset the application and secret keys for an API key. This allows to keep the API key configuration with a new set of authentication keys.

  1. Go to the “API configuration manager”,
  2. Click on the wished API key,
  3. Click on the “Reset” icon in the panel's title (top right),
  4. Confirm that you want to reset the API key,
  5. The API keys have been reset, and so new application and secret keys have been generated.

All applications using the resettled API key should be modified in order to use the new generated ones.

Delete an API key

  1. Go to the “API configuration manager”,
  2. Click on the “Delete” icon for the wished API key,
  3. Confirm that you want to delete the API key,
  4. The API key is deleted.

All applications using the deleted API key can no more communicate with the API.

Sign a request

When the BizDock instance is configured with the SIGNATURE mode, then all API requests should be signed. The computed signature is simply added in the request header.

This section explains how to manually sign a request. For sure, the different steps should be then code-included in the app which use the API.

1. Get the API key data

  1. Go to the “API configuration manager”,
  2. Click on the wished API key,
  3. The identity card of the API key is displayed.

Then keep the following data:

${secretKey}: The secret key
${applicationKey}: The application key

Example

${secretKey}=56mr7IG76reg742L6pGK7JSV4rCx6Liu4ZGhxbjsg5rlsablkYfok5DukYDmkbfvq5Hrq7nku4HuuZbumZPDr-S1healtua7vee3quCjrOm5puS9meOcjOy_m-uInOKDq--PgOi0qeKDm-arquKiqeu3r-eateaEouu8u-WFtOKutemDtOK_scm_8quQidSj7Z6_4oWu446L57G76aWe55ip7Y6W6bSM4qas4o666JKi66CH7Lut6pyc
${applicationKey}=76Sr7qiT6bGN6LmG4o-R7Y2A5J-j75aw6ry75a6f8a6whO2QkO-pue2EheSAsu6smOmYoeO-uO6UuOOlueuJsO-brOqjiOmUleSPleaWo-qum-m8ieG0juaXhOmws-eJiOi1v-GYiOWuueyRneaYpuGEiuyCjemZiOOssPCVsaLrjbfloLLijYzssIzls67ns7_lqaXrm5_pubnhpJrrl6vkjr3usJblr5DklJDmprXslajgu63lg5viiYs

2. Construct the signature's parameters

${method}: The HTTP method of the call (GET, POST…)
${url}: The full URL of the call
${body}: The request body (only for POST and PUT methods)
${timestamp}: The current timestamp in milliseconds

To get the current timestamp in milliseconds, you can use this online tool: http://www.timestampconvert.com

Example 1 (GET)

${method}=GET
${url}=https://localhost/api/core/portfolio-entry/10
${timestamp}=1432209909000

Example 2 (POST)

${method}=POST
${url}=https://localhost/api/core/actor
${body}={"firstName":"Johann","lastName":"Kohler","isActive":true}
${timestamp}=1432209909000

3. Construct the cipher

if POST and PUT:

${cipher}=${secretKey}+${method}+${url}+${body}+${timestamp}

Else:

${cipher}=${secretKey}+${method}+${url}+${timestamp}

The “+” characters are part of the cipher.

Example 1 (GET)

${cipher}=56mr7IG76reg742L6pGK7JSV4rCx6Liu4ZGhxbjsg5rlsablkYfok5DukYDmkbfvq5Hrq7nku4HuuZbumZPDr-S1healtua7vee3quCjrOm5puS9meOcjOy_m-uInOKDq--PgOi0qeKDm-arquKiqeu3r-eateaEouu8u-WFtOKutemDtOK_scm_8quQidSj7Z6_4oWu446L57G76aWe55ip7Y6W6bSM4qas4o666JKi66CH7Lut6pyc+GET+https://localhost/api/core/portfolio-entry/10+1432209909000

Example 2 (POST)

${cipher}=56mr7IG76reg742L6pGK7JSV4rCx6Liu4ZGhxbjsg5rlsablkYfok5DukYDmkbfvq5Hrq7nku4HuuZbumZPDr-S1healtua7vee3quCjrOm5puS9meOcjOy_m-uInOKDq--PgOi0qeKDm-arquKiqeu3r-eateaEouu8u-WFtOKutemDtOK_scm_8quQidSj7Z6_4oWu446L57G76aWe55ip7Y6W6bSM4qas4o666JKi66CH7Lut6pyc+POST+https://localhost/api/core/actor+{"firstName":"Johann","lastName":"Kohler","isActive":true}+1432209909000

4. Encrypt the cipher with the hash algorithm

The current hash algorithm is SHA-512:

${digest}=SHA-512(${cipher})

To encrypt a cipher, you can use this online tool: http://www.miniwebtool.com/sha512-hash-generator. The generated digest is given in hexadecimal.

Example 1 (GET)

${digest}=c29ab4ae33a608a7178af78ec02a930f4071e5686bb43a4059662bebb05924a99eec8f99516d45d37e84b0c674795f9231680aad6848ba9db3513141ba65635f

Example 2 (POST)

${digest}=00f1e45a169d2aa93a3c6298ef8b1fccf4d341091677196757fd1267d9e73a4ffa8d64b0faf553e51f59c4ce81a890ceceaa5b93d05aa38bcd7c5496e6f64ea1

5. Encode the digest in Base 64

${digest64}=Base64(${digest})

To encode a digest in Base 64, you can use this online tool: https://ostermiller.org/calc/encode.html
This should be done by 2 steps:

  1. Decode Hex
  2. Encode Base 64

Example 1 (GET)

${digest64}=wpq0rjOmCKcXiveOwCqTD0Bx5WhrtDpAWWYr67BZJKme7I+ZUW1F036EsMZ0eV+SMWgKrWhIup2zUTFBumVjXw==

Example 2 (POST)

${digest64}=APHkWhadKqk6PGKY74sfzPTTQQkWdxlnV/0SZ9nnOk/6jWSw+vVT5R9ZxM6BqJDOzqpbk9Bao4vNfFSW5vZOoQ==

6. Clean with URL-Safe the digest64

The followings characters should be replaced:

  • - instead of +
  • _ instead of /
  • = should be removed

Example 1 (GET)

${urlSafeDigest64}=wpq0rjOmCKcXiveOwCqTD0Bx5WhrtDpAWWYr67BZJKme7I-ZUW1F036EsMZ0eV-SMWgKrWhIup2zUTFBumVjXw

Example 2 (POST)

${urlSafeDigest64}=APHkWhadKqk6PGKY74sfzPTTQQkWdxlnV_0SZ9nnOk_6jWSw-vVT5R9ZxM6BqJDOzqpbk9Bao4vNfFSW5vZOoQ

7. Add the protocol version

The current protocol version is 1:

${signature}=#${protocolVerion}#${urlSafeDigest64}

Example 1 (GET)

${signature}=#1#wpq0rjOmCKcXiveOwCqTD0Bx5WhrtDpAWWYr67BZJKme7I-ZUW1F036EsMZ0eV-SMWgKrWhIup2zUTFBumVjXw

Example 2 (POST)

${signature}=#1#APHkWhadKqk6PGKY74sfzPTTQQkWdxlnV_0SZ9nnOk_6jWSw-vVT5R9ZxM6BqJDOzqpbk9Bao4vNfFSW5vZOoQ

8. Add the headers to the request

X-bizdock-timestamp=${timestamp}
X-bizdock-application=${applicationKey}
X-bizdock-signature=${signature}

Example 1 (GET)

X-bizdock-timestamp=1432209909000
X-bizdock-application=76Sr7qiT6bGN6LmG4o-R7Y2A5J-j75aw6ry75a6f8a6whO2QkO-pue2EheSAsu6smOmYoeO-uO6UuOOlueuJsO-brOqjiOmUleSPleaWo-qum-m8ieG0juaXhOmws-eJiOi1v-GYiOWuueyRneaYpuGEiuyCjemZiOOssPCVsaLrjbfloLLijYzssIzls67ns7_lqaXrm5_pubnhpJrrl6vkjr3usJblr5DklJDmprXslajgu63lg5viiYs
X-bizdock-signature=#1#wpq0rjOmCKcXiveOwCqTD0Bx5WhrtDpAWWYr67BZJKme7I-ZUW1F036EsMZ0eV-SMWgKrWhIup2zUTFBumVjXw

Example 2 (POST)

X-bizdock-timestamp=1432209909000
X-bizdock-application=76Sr7qiT6bGN6LmG4o-R7Y2A5J-j75aw6ry75a6f8a6whO2QkO-pue2EheSAsu6smOmYoeO-uO6UuOOlueuJsO-brOqjiOmUleSPleaWo-qum-m8ieG0juaXhOmws-eJiOi1v-GYiOWuueyRneaYpuGEiuyCjemZiOOssPCVsaLrjbfloLLijYzssIzls67ns7_lqaXrm5_pubnhpJrrl6vkjr3usJblr5DklJDmprXslajgu63lg5viiYs
X-bizdock-signature=#1#APHkWhadKqk6PGKY74sfzPTTQQkWdxlnV_0SZ9nnOk_6jWSw-vVT5R9ZxM6BqJDOzqpbk9Bao4vNfFSW5vZOoQ

Timestamp a request

The timestamp of a request is a security feature to prevent the execution of a same request at different times.

The API has a tolerance of 60 seconds, meaning a request is valid during this period under the condition of the timestamp generated by the client is timely aligned with the API clock.

To be sure the client clock is aligned with the API clock, a particular action “/api/system/time” could be called and returns the current timestamp of the API server. For sure the call doesn't need to include the timestamp.

Grant access computation

The grant access for an API action is depending of the given authentication headers.

  • All authentication headers are given
    • The API authentication mode could be SIGNATURE or APPLICATION_KEY_ONLY
    • The corresponding API key should authorize the action
  • The authentication headers “X-bizdock-timestamp” and “X-bizdock-application” are given
    • The API authentication mode should be APPLICATION_KEY_ONLY
    • The corresponding API key should authorize the action
  • No authentication header is given (usually the action is done by a User from the API Browser)
    • No restriction about API authentication mode
    • The User has the permission API_TESTER_PERMISSION
    • The API key is manually selected by the User, and should authorize the action and be testable

On top of that, it is considered that the authentication headers are correct.

API Browser

The API browser allows to test easily and quickly the different actions. It is also the full documentation to construct the requests and treat the responses.

The API browser is available only across BizDock and for an authorized (with the permission API_TESTER_PERMISSION) sign-in User.

The API browser interface is available from the “Integration” item inside the “Admin” menu. Then select the “API browser” item from the left menu.

It is possible to switch the using API keys thanks the “Tested application” dropdown menu.

API client

An API client should be soon available for JAVA and PHP languages.