External Actions API Overview

To execute actions in third-party systems, either extend an existing custom integration app, or create a new one. Check out how to create integration apps.

All communication between your custom app and Fibery services happens via standard hypertext protocols: HTTP or HTTPS. We expect all connectors to adhere to a particular API format outlined in this documentation but you are free to pick the underlying technology.

To register your app with Fibery, Provide a HTTP or HTTPS URI for your service. Please make sure your service is accessible from the internet, so that our custom apps gallery can communicate with it. We highly recommend using HTTPS for all endpoints and limit access to your services exclusively to IP addresses known to be from Fibery.

In essence, Fibery apps gallery service acts as a proxy between other Fibery services and the third-party provider with some extra logic for per-workspace storage and validation.

The installed app will be available for all users in your Fibery workspace. Users of other workspaces won't be able to see or use your custom app.

How to add, edit or delete

Your custom application can be registered the same way as integration application.

Domain

App schema

Each app should follow strict schema with the following structure (all fields are required):

Name	Type	Description	Example
name	string	Name	"MyApp"
website	string	Website	"http://myawesomeapp.com"
version	string	Version	"1.0.0"
description	string	Description	"My awesome app"
authentication	Array	Authentications	`[{id: "none", name: "no auth"}]`
sources	Array	Empty array	`[]`
responsibleFor	Object	Responsibilities	`{automations: true}`
actions	Array	Actions	`[]`

Action

Action model has the following structure:

Name	Type	Description	Required	Example
action	string	Identity of action	true	"Give the id for action"
name	string	Name of action	true	"Give the name for action"
description	string	Description of action	false	"Give the description for action"
args	Array	Action arguments	true	`[]`

Action Argument

Action argument model has the following structure:

Name	Type	Description	Required	Example
id	string	Identity of arg	true	"Give the id for argument"
name	string	Name of arg	true	"Give the name for argument"
description	string	Description of arg	false	"Give the description for argument"
type	string	Type of arg	true	Currently support `text` and `textarea`
textTemplateSupported	boolean	Whether templating is supported	false	`true` or `false`

Authentication

Authentication model represents type of authentication in app and has following structure:

Name	Type	Description	Required	Example
id	string	Identity of authenticaiton	true	"oauth" or "token"
name	string	Name of authentication	true	"Connection Settings"
description	string	Description of authentication	false	"Give the name for connection"
fields	Array	Authentication fields	false	`[{optional: false, id: "accountName", name: "Title", type: "text", description: 'Give the name for connection'}]`
responsibleFor	Object	Responsibilities. It's possible to narrow down responsibilities so account for external actions will not be available to data synchronizations and vice versa.	false	`{automations: true}`

If your app doesn't require authentication you should add authentication with id = "none". In the case you can omit fields.

Authentication field

Authentication field represents the field in account. So account that will send to API endpoints will consist of the authentication fields. Authentication field has following structure:

Name	Type	Description	Required	Example
id	string	Id of field. The id will be specified in account object.	true	"accountName"
name	string	Name of the field. Will be displayed in auth form.	true	"Title"
type	string	Type of the field	true	"text"
description	string	Description of the field	true	"Give the name for connection"
optional	boolean	Is the field optional	false	false
value	string	Default value of the field	false	null

Read about field types. Note that authentication field with some types requires more information to specify. For example, for highlightText type you also need to specify editorMode in authentication field.

Fields

Fields in Fibery integration app denote either user-supplied fields or fields within an information schema. There are various types of fields that each represent a different type of data. Fields are also used internally to denote information both required and optional for accounts and filters.

Field Types

The table below lists the types of fields referred to in the Fibery integration app REST API.
The first column denotes the string name of the type as expected in the API, the second column the type of underlying data, the third column any comments and remarks for each field type and the last one show additional options that may be specified.

type	datatype	comments and remarks	Additional options
text	string	UTF-8 encoding	-
number	number	can be decimal, integer, or float	-
bool	boolean	validates as true/false	-
password	string	only used in account schemas, rendered as a password input	-
link	- (used for view)	show link to external source	Need to specify "value" field. It should contain link, for example "http://test.com".
highlightText	string	text with syntax highlight (json and sql supported for now)	Need to specify "editorMode" field. For now "json" and "sql" are supported.
datebox	date	single date selector
date	date	date selection with support of Date range grammar	-
oauth	- (used for view)	display OAuth form	-
list	variant	allows to select value from multiple options	Optional "datalist_requires" can be specified. For example "datalist_requires" = ["owner"] means that fetching the list depends on "owner" field.
multidropdown	Array	allows to select multiple values from dropdown list	Optional "datalist_requires" can be specified. For example "datalist_requires" = ["owner"] means that fetching the list depends on "owner" field.

A Special Note on Dates

Dates, both with and without times, that are parsed as a result of user-input (through the Date range grammar) are timezone-naive objects. Dates received from connected applications may be either aware or naive of timezones and should represent those dates as strings in an ISO-8601 format.

REST Endpoints

Below are a list of the HTTP endpoints expected in an integration application.

Required

GET /: returns app information
POST /validate: performs validation of the account
POST /api/v1/automations/action/execute: executes action

Optional

GET /logo: returns an image/svg+xml representation of the application's logo

GET /

{
    "version": "1.0",  // string representing the version of your app
    "name": "My Super Application",  // title of the app
    "description": "All your base are belong to us!", // long description
    "authentication": [], // list of possible account authentication approaches
    "sources": [], // empty error
    "responsibleFor": { // app responsibility
        "dataSynchronization": true // indicates that app is responsible for data synchronization
    }
}

GET "/" endpoint is the main one which returns information about the app. You can find response structure here. Response example:

Authentication Information

{
    "authentication": [
        {
            "id": "basic", // identifier
            "name": "Basic Authentication", // user-friendly title
            "description": "Just using a username and password", // description
            "fields": [  //list of fields to be filled
                {
                    "id": "username",  //field identifier
                    "title": "Username",  //friendly name
                    "description": "Your username, duh!",  //description
                    "type": "text",  //field type (text, password, number, etc.)
                    "optional": true,  // is this a optional field?
                },
                /* ... */
            ]
        }
    ]
}

The authentication object includes all account schema information. It informs the Fibery front-end how to build forms for the end-user to provide required account information. This property is required, even if your application does not require authentication. At least one authentication object must be provided within array.

In case when application doesn't require authentication, the fields array must be omitted. Read more about fields here.

Important note: if your app provides OAuth capabilities for authentication, the authentication identifiers must be oauth and oauth2 for OAuth v1 and OAuth v2, respectively.
Only one authentication type per OAuth version is currently supported.

POST /validate

Incoming body:

{
    "id": "basic", // identifier for the account type
    "fields": { //list of field values to validate according to schema
        "username": "test_user",
        "password": "test$user!",
        /*...*/
    }
}

Success Response:

{"name": "Awesome Account"}

If the account is invalid, the app should return HTTP status 401 (Not Authorized) with a simple JSON object containing an error message:

Failure Response:

{"message": "Your password is incorrect!"}

This endpoint performs account validation when setting up an account for the app and before any actions that uses the account. The incoming payload includes information about the account type to be validated and all fields required:

If the account is valid, the app should return HTTP status 200 with a JSON object containing a friendly name for the account:

Refresh Access Token

Refresh Access Token Request:

{
    "id": "oauth2",
    "fields": {
        "access_token": "xxxx",
        "refresh_token": "yyyy",
        "expire_on": "2018-01-01"
    }
}

Response sample after token refresh:

{
    "name": "Awesome account",
    "access_token": "new-access-token",
    "expire_on": "2020-01-01"
}

In addition this step can be used as a possibility to refresh access token. The incoming payload includes refresh and access token, also it can include expiration datetime. Response should include new access token to override expired one.

POST /api/v1/automations/action/execute

Executes specific action with specified parameters. In case of success response just return empty object with success status code

Request body sample:

{
  "action": {
    "action": "create-pull-request",
    "args": {
      "repo": "me/my-repo",
      "name": "new-branch-name",
      "ref": "main"
    }
  },
  "account": {
    "username": "test_user",
    "password": "test$user!"
  }
}

Success response:

{}

Failure response:

{
  "message": "Pull request with specified name exists."
}

GET /logo

OPTIONAL

The /logo endpoint is used to provide a SVG representation of a connected application's logo. This endpoint is entirely optional. Valid responses are a HTTP 200 response with a image/svg+xml content type, a HTTP 204 (No Content) response if there is no logo, or a 302 redirect to another URI containing the logo. If no logo is provided, or an error occurs, the application will be represented with our default app logo.

OAuth

if your app provides OAuth capabilities for authentication, the authentication identifiers must be oauth and oauth2 for OAuth v1 and OAuth v2, respectively. Only one authentication type per OAuth version is currently supported.

OAuth v1

POST /oauth1/v1/authorize

The POST /oauth1/v1/authorize endpoint performs obtaining request token and secret and generating of authorization url for OAuth version 1 accounts.

Request body sample:

{
  "callback_uri": "https://oauth-svc.fibery.io/callback?state=xxxxxxx"
}

Included with the request is a single body parameter, callback_uri, which is the redirect URL that the user should be expected to be redirected to upon successful authentication with the third-party service. callback_uri includes query parameter state that MUST be preserved to be able to complete OAuth flow by Fibery.

Response body sample:

{
  "redirect_uri": "https://trello.com/1/OAuthAuthorizeToken?oauth_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&name=TrelloIntegration",
  "token": "xxxx",
  "secret": "xxxx"
}

Return body should include a redirect_uri that the user should be forwarded to in order to complete setup, token and secret are granted request token and secret by third-party service. Replies are then POST'ed to /oauth1/v1/access_token endpoint.

Note: The OAuth implementation requires the account identifier to be oauth for OAuth version 1.

Note: If service provider has callback url whitelisting than https://oauth-svc.fibery.io?state=xxxxx has to be added to the whitelist.

POST /oauth1/v1/access_token

Request body sample:

{
  "fields": {
    "access_token": "xxxx",
    // token value from authorize step
    "access_secret": "xxxxx",
    // secret value from authorize step
    "callback_uri": "https://oauth-svc.fibery.io?state=xxxxx"
  },
  "oauth_verifier": "xxxxx"
}

The POST /oauth1/v1/access_token endpoint performs the final setup and validation of OAuth version 1 accounts. Information as received from the third party upon redirection to the previously posted callback_uri are sent to this endpoint, with other applicable account information, for final setup. The account is then validated and, if successful, the account is returned; if there is an error, it is to be raised appropriately.

The information that is sent to endpoint includes:

fields.access_token - request token granted during authorization step
fields.access_secret - request secret granted during authorization step
fields.callback_uri - callback uri that is used for user redirection
oauth_verifier - the verification code received upon accepting on third-party service consent screen.

Response body sample:

{
  "access_token": "xxxxxx",
  "refresh_token": "xxxxxx",
  "expires_on": "2020-01-01T09:53:41.000Z"
}

Response can include any data that will be used to authenticate account and fetch information.

Tip: You can include parameters with refresh_token and expires_on and then on validate step proceed with access token refresh if it is expired or about to expire.

OAuth v2

POST /oauth2/v1/authorize

Request sample

{
  "callback_uri": "https://oauth-svc.fibery.io",
  "state": "xxxxxx"
}

The POST /oauth2/v1/authorize endpoint performs the initial setup for OAuth version 2 accounts using Authorization Code grant type by generating redirect_uri based on received parameters.

Request body includes following parameters:

callback_uri - is the redirect URL that the user should be expected to be redirected to upon successful authentication with the third-party service
state - opaque value used by the client to maintain state between request and callback. This value should be included in redirect_uri to be able to complete OAuth flow by Fibery.

Response example:

{
  "redirect_uri": "https://accounts.google.com/o/oauth2/token?state=xxxx&scope=openid+profile+email&client_secret=xxxx&grant_type=authorization_code&redirect_uri=something&code=xxxxx&client_id=xxxxx"
}

Return body should include a redirect_uri that the user should be forwarded to in order to complete setup.
Replies are then POST'ed to /oauth2/v1/access_token endpoint.

Note: The OAuth implementation requires the account identifier to be oauth2 for OAuth version 2.

Note: If service provider has callback url whitelisting than https://oauth-svc.fibery.io has to be added to the whitelist.

POST /oauth2/v1/access_token

Request body sample:

{
  "fields": {
    "callback_uri": "https://oauth-svc.fibery.io"
  },
  "code": "xxxxx"
}

The POST /oauth2/v1/access_token endpoint performs the final setup and validation of OAuth version 2 accounts. Information as received from the third party upon redirection to the previously posted callback_uri are sent to this endpoint, with other applicable account information, for final setup. The account is then validated and, if successful, the account is returned; if there is an error, it is to be raised appropriately.

The information that is sent to endpoint includes:

fields.callback_uri - callback uri that is used for user redirection
code - the authorization code received from the authorization server during redirect on callback_uri

Response body sample:

{
  "access_token": "xxxxxx",
  "refresh_token": "xxxxxx",
  "expires_on": "2020-01-01T09:53:41.000Z"
}

Response can include any data that will be used to authenticate account and fetch information.

Tip: You can include parameters with refresh_token and expires_on and then on validate step proceed with access token refresh if it is expired or about to expire.