To get the tFLOW API credentials, go to the user profile and click on “Show API credentials” link at the bottom of the page. You will see API key and Secret key. Both keys are required to access the tFLOW API.

tFLOW API uses a subset of OAuth2.0 authentication protocol.

First, call the “Get Access token” method by sending POST request to http://<site>/oauth/access_token, sending three parameters: grant_type (must be always client_credentials), client_id, and client_secret. The latter two parameters are the API key and Secret key, respectively, which can be shown in the user profile as described in Getting API Credentials above.

On success, the call will return an access token information like this:

{
    "access_token": "RDdhuIuHyRQKKtLQmJteNT3D0xOzqvYwib01BGLi",
    "token_type": "Bearer",
    "expires_in": 3600
}

Once received, the access token must be specified in the Authorization HTTP header when calling any other API methods, like this:

Authorization: Bearer RDdhuIuHyRQKKtLQmJteNT3D0xOzqvYwib01BGLi

When accessing tFLOW API, the URI structure should be as follows:

http://<instance>/api/v2/<entity>/<action_or_additional_params>

http://<instance>/apidoc

For example, to create a job on tethra.local instance, one should send a POST request to URI

http://tethra.local/api/v2/job/create

To get information about a job with ID = 123, need to send a GET request to URI

http://tethra.local/api/v2/job/123

Apart parameters included into the URI, each method may accept other parameters, which may be mandatory or optional. The parameters may be passed using several forms:

1. As a query string according to the RFC 3986. This is convenient for HTTP GET methods.
2. As JSON code in the request body, like this:

   {
      "param1": "value1",
      "param2": "value2"
   }

   This is useful for HTTP POST methods.

3. As JSON code assigned to _json parameter:

   _json={"param1":"value1","param2":"value2"}

This works for HTTP GET and POST methods, but especially useful when an HTTP POST method requires uploading a file, thus the requiest must have multipart/form-data encoding.

All string parameters passed to the tFLOW API must be in UTF-8 character encoding.

All date/time values must be specified according to ISO 8601 standard, for example:

"2015-10-22T15:12:35+07"

Data returned from tFLOW API methods are always in JSON format, except when the API method is supposing to download a file.

The actual set of attributes returned by an API method may depend on the user account permissions which is used to access the API.

Each entity of type User represents a user account which is required to access the system. Access to the tFLOW system, either via UI or via API, is always performed under a user account, applying the account's permissions.

Apart obvious attributes, like email or name, each user has a set of more complex attributes:

• Each user is owned by some client company. The ID of the owning company is stored to client_id attribute. Users owned by instance company are referred to as instance users.
• Each user has associated list of client companies which the user is able to see. IDs of those companies are stored in visibleClientIds attribute. Note that the owning company is always included to the list.
• Each user belongs to a particular role, and the ID of that role is stored in role_id attribute.
• Each user has associated list of email alerts which are allowed to automatically send by the system on various events. Email alerts are described here.

Each entity of type Client represents a client company account. There is one special company account - instance owner company or simply instance company. Such a company is created when initializing a new tFLOW instance and generally cannot be changed later.

Users owned by the instance company are called instance users. Instance users have more permissions than plain users.

Product is a combination of three automation scripts: * automation script used for production processing (preflight) (mandatory) * automation script used for making proofs (optional, a default automation script of corresponding type is used when not specified) * automation script used for finishing (optional, not used in some configurations)

Each order and job must have a valid reference to a product. When creating job, it by default inherits product from the containing order.

Role is basically a set of permissions. These statements are about roles: * Roles are belonging to a particular client * Each user can be assigned to one role * User can be assigned only to role which has the same owner company

tFLOW production queue is a connection between tFLOW and tBot (or Turbine). When job is sent to a production queue, the production file from last revision of the job is downloaded by tBot (or Turbine) and passed to final processing steps, such as printing or cutting.

tFLOW queues are automatically registered within the system by tBot.

Webhooks are used to automatically call application's code by tFLOW API when a particular event is happen, so it is implementation of a “Publish/Subscribe” paradigm. The API client application subscribes to event by specifying the event name and URL. After that, tFLOW API publishes events by calling the specified URL.

There is a full list of currently available events:

Order acts a container for jobs. There are statements about orders:

• Orders are always belonging to some company. Once order created, the owning company cannot be changed.
• Most of order properties are inherited by enclosed jobs by default. However, it is possible to override inherited defaults.

Job is the main entity in the tFLOW system. It represents a single artwork file which should be tracked, approved (or cancelled), and finally sent to production.

• Each job belongs to an order. It is not possible to move jobs from one order to another.
• There could be zero or more Revisions in the job.
• Each job is assigned to one or more users. The user who initially created the job is assigned automatically.
• Only assigned users can execute transitions on the job.

Revision representing separate versions of an artwork files uploaded to the job. Each job may have zero or more revisions. There is a way to get list of all revisions of a job, but most usual is the last revision.

When uploading an artwork to a job, actually one of the following transitions is executed: upload_first_revision or upload_next_revision, depending on the current job state.

A comprehensive description of tFLOW Workflows can be found here.