free demo

Getting started

The Iron Bridge Developer Docs will guide you through connecting to our API, testing, and deploying your API integration for production use.  We offer a HTTP-based, REST API with JSON payloads.  Most API resources have sub-second response times.

To get started, contact your Iron Bridge representative and request access to our API. In the following sections, we’ll describe various assets of our API, recommend integration best practices, and provide usage examples to get you up and running.

Authentication

OAuth 2.0

The Iron Bridge API uses OAuth 2.0 with the 'Client Credentials' grant type making access to your data secure and simple. Read more about OAuth 2.0 here.

This service authorizes a principle to access the API by authenticating principle id and principle secret that have been encoded (Base64) and passed into the header as encrypted (HTTPS) Basic authentication.

Please note all request MUST be over HTTPS

To authenticate to the API take the principle id and principle secret given to you by your account representative and store them in a safe place. With these values in hand, call this api resource by following the below steps:

  1. build a string with the following format: "principle_id:principle_secret"
  2. base64 encode the above string

Example Javascript:

new Buffer(exampleid:examplesecret).toString('base64')

Example Java 8:

Base64.getEncoded().encodeToString("exampleid:examplesecret".getBytes("utf-8"));
3. Take the output of base64 encoding above and place these into your Authorization header
Authorization: Basic ZXhhbXBsZWlkOmV4YW1wbGVzZWNyZXQ=
4. Submit (HTTP POST) the Authorization header to /oauth2/token
5. Take the access_token received and pass this into each subsequent request headers as
Authorization: Bearer ZXhhbXBsZWlkOmV4YW1wbGVzZWNyZXQ=
POST
https://app.nuvolahubapi.io/oauth2/token

Header

Field Type Description
Authorization String "Authorization": "Basic dGVzdHVzZXI6dGVzdHBhc3N3b3Jk"

Success 200

Field Type Description
user_id Number id of user authenticated and authorized
provider_id Number id assigned to authenticated provider if available, admin accounts will not be assigned a provider_id
username String principle used to authenticate
access_token String access_token assigned to pass into further request for access
expires Date date at which no access will expire the access_token and require re-authorization. YYYY-MM-DD HH:mm:ss.SS
role String assigned principle role
token_type String type of token assigned
last_login Date date of last login by principle
HTTP/1.1 200 OK
{
 "user_id": 1,
 "provider_id": null,
 "username": "exampleuser",
 "access_token"
: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
 "expires"
: "2017-04-02 15:31:22.22",
 "role"
: "admin",
 "token_type"
: "bearer",
 "last_login"
: "2017-04-02 11:01:13.42"
}
curl -X POST \  
https://app.nuvolahubapi.io/oauth2/token \
-H 'Authorization: Basic Auth <Your Token>'

Error 401

Name Type Description
Forbidden String Resource forbidden
HTTP/1.1 401 Unauthorized
{
 "error": "Unauthorized",
 "message"
: "Not authorized to use this service: {path}"
}

Rate Limiting

Per User/ Access Token

Rate limiting is handled per user or per access_token. The limit is defaulted to 80 requests within a 60 second window. Exceeding this limit will result in the following error:

Please note that all API responses contain rate limiting information in the response headers:

  • x-rate-limit-limit : total number of requests allowed within the window
  • x-rate-limit-remaining: remaining number of requests allows within current window
  • x-rate-limit-reset: time when rate-limiter will reset (UTC seconds-since-epoch)

Webhooks

Callback URL


What is a "webhook"? When you send a text message, do you stare at your phone all day waiting for a response or do you wait for your phone to notify you that there’s a new message to read?  Think of a webhook as a means for our system to let you know when data is ready instead of having you wait around for it.

To use a webhook, register the URL that you would like us to talk to using the below API specifications.

Service: [service_events]
Submissions: [create, update]

Access our Pub Hub 2.0 API Service Specs: