This is a REST-style API that uses serialized JSON and OAuth2 authentication. We are very interested in making our API, and this documentation, as good as it possibly can be so please send any feedback to happytohelp@resourceguruapp.com. Any thoughts or suggestions will be gratefully received.

Encoding

The API expects all data to be UTF-8 encoded.

The Base URL

All requests start with the https://api.resourceguruapp.com/ base URL.

• All requests are done via SSL.
• All responses are in JSON.

Making a Basic Request

With the exception of Accounts all requests must be prefixed with the Account URL ID.

To make a request for all the Resources on the Example Corp account, the request URL will look something like this https://api.resourceguruapp.com/v1/example-corp/resources.

Each registered application is allowed up to 200 requests per minute. If this limit is exceeded, the server will respond with a 429 Rate Limit Exceeded error for any extra requests made within that minute.

When you make a request, the server response will include three important headers related to rate limiting:

• Retry-After: This header indicates how many seconds you should wait before sending another request if the rate limit has been exceeded.

• X-RateLimit-Remaining: This header tells you how many more requests you can make within the current minute without exceeding the rate limit.

• X-RateLimit-Limit: This header shows the maximum number of requests that can be made per minute. Normally, this is set to 200.

• You can request up to 20 OAuth2 tokens per minute for a single user.
• The daily limit for issuing OAuth2 tokens to a single user is 1,000.

Resource Guru provides headers to allow CORS requests to the API. You will need to authenticate using a valid OAuth2 token.

• 200 OK
• 201 Created
• 204 No Content
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 422 Unprocessable Entity
• 5xx Resource Guru is having trouble

In order to make authenticated calls to Resource Guru's API, your application must first obtain an OAuth2 access token. To register your app go to https://app.resourceguruapp.com/developers.

Resource Guru implements OAuth2 with the authentication code flow.

Once you have authenticated, you can get information about the authenticated user by calling GET https://api.resourceguruapp.com/v1/me. More details about the request and response are available below.

Getting access to a user's Resource Guru account requires going through a step of authentication. We offer OAuth2 as the standard way to authenticate with our API as this offers a simple flow for users to allow app access without you having to store their credentials.

For convenience, Resource Guru's API will accept credentials provided through the HTTP Basic Authorization header. This is intended for exploration of the API only. We apply a global rate limit to HTTP Basic authorizations based on compute resources available at the given time, and provide no SLA. HTTP Basic authentication may be disabled without warning.

If your account is configured to require SSO for logins, API access through OAuth2 is only available when authenticating as the account owner. This restriction ensures that users who have been removed from your identity provider (IdP) aren't able to continue accessing your Resource Guru account with unexpired API tokens.

We recommend using an OAuth2 library for the platform you're working with, rather than working from scratch. A fairly comprehensive list of libraries can be found here.

1. Register an app at developers.resourceguruapp.com. Your app will be assigned a client_id and client_secret that will be used to identify your app when users authenticate with the API. You'll need to provide a redirect_uri where we'll send the verification code for authentication. Just use a fake URL like http://localhost/oauth if you haven't got one yet. Any Redirect URI given must be secure (HTTPS) unless it redirects to localhost.

2. Configure your OAuth2 library to use the client_id, client_secret and redirect_uri for your app. You'll need to configure these URLs as well:

   • https://api.resourceguruapp.com/oauth/authorize to request authorization (must be requested with an HTTP GET request).
   • https://api.resourceguruapp.com/oauth/token to retrieve tokens (must be requested with an HTTP POST request).

3. Authenticate with the API. We'll provide code samples using the intridea/oauth2 library in Ruby.

   Quick start using user's login credentials

   This method is only recommended for private apps, such as data imports and exports or internal business reporting. It's useful to get started quickly without all of the overhead of OAuth2 though, which makes it great for exploration. This should not be used for integrating 3rd party apps with Resource Guru as it requires knowing the user's private credentials.

   We support the OAuth2 password grant type. To authenticate, make an HTTP POST to /oauth/token with the following:

   {
     "grant_type"    : "password",
     "username"      : "user@example.com",
     "password"      : "secret",
     "client_id"     : "the_client_id",
     "client_secret" : "the_client_secret"
   }
   

   You'll receive the access token back in the response:

   {
     "access_token": "the_oauth_access_token",
     "refresh_token": "the_oauth_refresh_token",
     "token_type": "bearer",
     "expires_in": 604800
   }
   

   To use this with the OAuth2 Ruby library is easy:

   client = OAuth2::Client.new(client_id, client_secret, site: "https://api.resourceguruapp.com")
   token = client.password.get_token("user@example.com", "secret")
   token.get("/v1/example-corp/resources")
   

   Recommended authentication method using an authorization code

   The password grant method shown above is great for getting started quickly, but is impractical for apps that require users to authenticate with Resource Guru as you would have to store the user's Resource Guru login credentials.

   We support the standard auth code flow as well. Here is a code sample in Ruby of how to authenticate this way.

   require 'oauth2'
   
   client_id = ENV["CLIENT_ID"]
   client_secret = ENV["CLIENT_SECRET"]
   redirect_uri = ENV["REDIRECT_URI"]
   
   client = OAuth2::Client.new(client_id, client_secret, site: 'https://api.resourceguruapp.com')
   
   puts client.auth_code.authorize_url(redirect_uri: redirect_uri)
   

   Go to the URL provided to authorize with the API. This is the URL you'll direct users to to allow your app to access the API. When you've authorized with the API, the browser will be redirected to the redirect_uri you provided and the authorization code will be sent as a parameter in the URL. For example if your redirect_uri was https://localhost/oauth/callback, the user will be redirected to https://localhost/oauth/callback?code=<the code>

   Use this code to retrieve an access token and refresh token:

   code = "code sent to the redirect_uri in the previous step"
   access_token = client.auth_code.get_token(code, redirect_uri: redirect_uri)
   access_token.get("/v1/example-corp/resources")
   

   Save the values returned as access_token.token, access_token.refresh_token and access_token.expires_at for later usage.

   To connect to the API with a known token:

   client_id = ENV["CLIENT_ID"]
   client_secret = ENV["CLIENT_SECRET"]
   redirect_uri = ENV["REDIRECT_URI"]
   oauth_token = ENV["OAUTH_TOKEN"]
   refresh_token = ENV["REFRESH_TOKEN"]
   expires_at = ENV["EXPIRY"]
   
   client = OAuth2::Client.new(client_id, client_secret, site: 'https://api.resourceguruapp.com')
   access_token = OAuth2::AccessToken.new(client, oauth_token, refresh_token: refresh_token, expires_at: expires_at)
   access_token.get("/v1/example-corp/resources")
   

   In the above example using the token expiry time stamp is optional, but the OAuth2 library will automatically handle refreshing tokens if it is provided.

4. Tokens expire after 7 days and need to be refreshed. When authenticating, a refresh token and expiration timestamp is provided. Use the refresh token to retrieve a new access token. Most OAuth2 client libraries will handle this automatically.

   client_id = ENV["CLIENT_ID"]
   client_secret = ENV["CLIENT_SECRET"]
   redirect_uri = ENV["REDIRECT_URI"]
   oauth_token = ENV["OAUTH_TOKEN"]
   refresh_token = ENV["REFRESH_TOKEN"]
   expires_at = ENV["EXPIRY"]
   
   client = OAuth2::Client.new(client_id, client_secret, site: 'https://api.resourceguruapp.com')
   access_token = OAuth2::AccessToken.new(client, oauth_token, refresh_token: refresh_token, expires_at: expires_at)
   new_access_token = access_token.refresh
   new_access_token.get("/v1/example-corp/bookings")
   

   The old access token will be expired immediately and the new access token will have to be used from that point on. Make sure you save the new access token, refresh token and expiration timestamps when doing this.

Python 3

from urllib.parse import urlencode
import json
import requests

client_id     = 'APPLICATION_CLIENT_ID'
client_secret = 'APPLICATION_SECRET'
redirect_uri  = 'REDIRECT_URI'
authorize_url = "https://api.resourceguruapp.com/oauth/authorize?client_id=%(client_id)s&redirect_uri=%(redirect_uri)s&response_type=code" % locals()

# Visit the Auth URL -> authorize_url defined above
# Get code token after authorizing
returned_code = input("Enter the code from the authorization step: ")

parameters = {
  'client_id': client_id,
  'client_secret': client_secret,
  'code': returned_code,
  'grant_type': "authorization_code",
  'redirect_uri': redirect_uri
}

token_url = 'https://api.resourceguruapp.com/oauth/token'
token     = requests.post(token_url, urlencode(parameters)).json()
headers   = { "Authorization": "Bearer " + token['access_token'] }

resources = requests.get("https://api.resourceguruapp.com/v1/example-account-id/resources", headers=headers).json()

# Now let's play in an interactive console
import code;code.interact(local=dict(globals(),**locals()))

Bash

#!/bin/bash

client_id='APPLICATION_CLIENT_ID'
client_secret='APPLICATION_SECRET'
redirect_uri='REDIRECT_URI'
authorize_url="https://api.resourceguruapp.com/oauth/authorize?client_id=$client_id&redirect_uri=$redirect_uri&response_type=code"
token_url='https://api.resourceguruapp.com/oauth/token'

echo "Please follow the given link: $authorize_url"
echo "Please provide the given code, followed by [ENTER]:"

read code

token_data=`curl --data "grant_type=authorization_code" --data-urlencode "client_id=$client_id" --data-urlencode "client_secret=$client_secret" --data-urlencode "code=$code" --data-urlencode "redirect_uri=$redirect_uri" $token_url`
token=`echo $token_data | jsawk 'return this.access_token'`

resources_url="https://api.resourceguruapp.com/v1/example-account-id/resources"

echo `curl -H "Authorization: Bearer $token" $resources_url`

Ruby

require "oauth2"

client_id = "APPLICATION_CLIENT_ID"
client_secret = "APPLICATION_SECRET"
redirect_uri = "REDIRECT_URI"

client = OAuth2::Client.new(client_id, client_secret, { site: { url: 'https://api.resourceguruapp.com'}})
authorize_url = client.auth_code.authorize_url(redirect_uri: redirect_uri)

# Visit the Auth URL -> authorize_url defined above to get the code
puts "Enter the code from the authorization step"
code = gets.strip

access_token = client.auth_code.get_token(code, redirect_uri: redirect_uri)

access_token.get("/v1/example-account-id/resources")

# Now let's play in an interactive console
require "IRB"
IRB.start

The ISO8601 format is used for dates and times throughout the Resource Guru API.

An ISO8601 date string is formatted as YYYY-MM-DD. For example: 2020-01-31.

An ISO8601 date time string is formatted as YYYY-MM-DDTHH:mm:ssZ. For example: 2020-01-31T12:34:56Z

Days of the week are represented as integers from 0-6.

Timezone references in the Resource Guru API use the names of Rails ActiveSupport timezones.

Operations for retrieving accounts.

Operations for retrieving the activity log for an event.

Operations for creating, retrieving or modifying the bookings for an account.