Workbench API (v2)

Introduction

URL: https://workbench.expel.io/api/v2

The Workbench Public API gives organizations the means to access and manipulate their Expel Workbench data using custom API clients. Want to extract information into your reporting system? Use this API! Have some innovative data science idea for analyzing Expel alert evidence? Use this API! Want to write your own custom browser plugin to make your team's analysts more efficient? Use this API!

The majority of the Workbench API implements the jsonapi spec.

jsonapi-server Post Processing

Only the routes that do not follow the JSON:API spec have been defined in the 'CUSTOM ROUTES' section below.

Authentication

User authentication

User authentication is accomplished using the /login API route. This route is used to pass user authentication credentials to the API. If authentication is successful, the /login returns a temporary (default: 13 hours) Bearer Token (access_token) that can be used to access the API.

The request body requires a flat json document with three properties: username, password, and an otp.

    curl 'https://workbench.expel.io/auth/v0/login' \
        -X POST \
        -H 'Content-Type: application/json' \
        --data-binary '{ "username": "sample_user@expel.io", "password": "secret", "otp": "123456" }'
    {
      "access_token": "<access_token>",
      "created_at": 1532537770,
      "expires_in": 46800,
      "token_type": "bearer",
      "user_id": "0796cba8-3c96-4984-8d51-22222381f870",
      "username": "sample_user@expel.io",
      "role": "expel_admin",
      "organization_id": "2ca75135-5a84-4298-b8ba-b5e0fd6fb576",
      "realm": "public"
    }

Note: as an alternative to the otp property, you can pass an X-ExpelInc-Otp http request header with the otp token. This is useful when interfacing with single login frameworks

The otp property or X-ExpelInc-Otp header must be populated with the correct 6 digit two-factor authentication code (e.g. Google Auth code) for authentication to succeed. If the Workbench API is not given an OTP token, authentication will fail with a 401 with the response header X-ExpelInc-Otp set to required.

After authentication, the rest of the API may be accessed using the Bearer Token returned in the access_token field. Pass that token back to the API in the Authorization header using Bearer as the credential type.

    curl 'https://workbench.expel.io/api/v2/expel_alerts' \
        -H 'Authorization: Bearer <access_token>'

Browser authentication

Browser authentication uses the same user authentication mechanism described in the previous sections of this document. However, if you wish for the Workbench API to set a browser cookie in addition to a Bearer Token, you can pass the optional X-Accepts-Auth-Cookie http request header set to true.

   curl 'https://workbench.expel.io/auth/v0/login' \
       -D - -o /dev/null \
       -X POST \
       -H 'Content-Type: application/json' \
       -H 'X-Accepts-Auth-Cookie: true' \
       --data-binary '{ "username": "sample_user@expel.io", "password": "secret", "otp": "123456" }'
   . . .
   Set-Cookie: token=<access_token>; Path=/; Expires=Thu, 26 Jul 2018 06:05:41 GMT; HttpOnly; Secure
   . . .

That cookie will then be used to authenticate all future API calls in a browser. The cookie will expire in tandem with the access_token.

API key authentication

API keys are self-service via Workbench by going to Organization Settings > Service Accounts (only users with API access can view this page and generate API keys - contact sales to upgrade). The API key amounts to a Bearer access_token without an expiration that is tied to a specific service account with a standard admin or analyst role. This is particularly useful for daemon services, automated scripts, ETL jobs, etc. API key Bearer tokens are used in the same manner as the temporary user Bearer tokens as described in the previous sections of this document.

    curl 'https://workbench.expel.io/api/v2/expel_alerts' \
        -H 'Authorization: Bearer <api_key>'

CRUD operations