NAV Navbar

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

Optional

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."
}

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:

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:

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:

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.