PebblePad : API documentation

API Documentation

API Documentation

Introduction

The PebblePad API is REST based using OAuth2 authentication. We suggest that you try out tools such as the Postman - REST Client (Packaged App) when first using a REST API.

We have provided two methods for the authentication, standard authentication and "Service Account" authentication. Service Account authentication has the benefits that there is no need to login to PebblePad to authenticate or concern yourselves with scopes or a client id or make extra calls for the "Access Token". We provide your directly with the "Access Token" with the necessary scope.

Every call to the API, requires the use of an Access Token, the documentation leads you through these two methods starting with the Service Account below and the manual authentication approach further on. But before you make any calls you need to ensure that you are calling the correct install as described.

Your organisation's installation location

The PebblePad API is available on multiple installations around the world, therefore, you will need to use the correct OAuth2 and API Uris for your organisation's installation location.

United Kingdom https://v3.pebblepad.co.uk/login/OAuth2/
https://v3.pebblepad.co.uk/api/
United States of America https://pebblepad.com/login/OAuth2/
https://pebblepad.com/api/
Australia https://v3.pebblepad.com.au/login/OAuth2/
https://v3.pebblepad.com.au/api/
TAQAS (Testing) https://v3test.pebblepad.com/login/OAuth2/
https://v3test.pebblepad.com/api/

Getting Started with a Service Account

If you are using a Service Account then a PebblePad support engineer has provided you with an Access Token and a Refresh Token. You will most probably need to refresh the token before it can be used because the Access Token expires after 60 minutes, starting from the time it was created. To do this follow the instructions and example call that follows:

Usage Limits

Rating limits operate on a rolling one minute window with a different limit per HTTP Method. Exceeding any of the limits will result in a 429 status code and an error response. In addition to the rate limits, there is also a concurrency limit applied. Exceeding this limit will also result in a 429 status and an error response. Any calls ending in an error response will not be processed and will require resubmitting.

Please see the table below to see the current rate limits for your region. These calls do not require OAuth.

United Kingdom https://v3.pebblepad.co.uk/api/1.1/Info/GetRateLimits
United States of America https://pebblepad.com/api/1.1/Info/GetRateLimits
Australia https://v3.pebblepad.com.au/api/1.1/Info/GetRateLimits
TAQAS (Testing) https://v3test.pebblepad.com/api/1.1/Info/GetRateLimits

If you wish to parse these limits, the format is as follows.

{  
   "TotalConcurrentRequests":4,
   "PutRatePerMinute":100,
   "PostRatePerMinute":100,
   "GetRatePerMinute":200,
   "DeleteRatePerMinute":140,
   "MethodLimits":[  
      {  
         "ControllerName":"ExampleController",
         "MethodName":"ExampleMethod",
         "RatePerMinute":5
      }
   ]
}
                    

Each request you make will contain the following headers on the response. All headers are generated on end of the call any may contain newer recieved calls in concurrent environments.

X-Rate-Limit The current limit for requests you can make in a rolling 1 minute window
X-Rate-Remaining The remaining number of calls you can make before hitting the limit
X-Concurrency-Limit The current limit for concurrent calls regardless of method
X-Concurrency-Remaining The remaining number of concurrent calls you can make before hitting the limit, excluding the current finished call

Refreshing your Access Token

This is where you obtain you another Access Token should you need to - using your previously given Refresh Token.

Uri

/login/OAuth2/TokenEndpoint

Verb

POST

Parameters

grant_type required "refresh_token" - the type of token request
refresh_token required This will be the refresh_token provided to you by Support, the one you received in Step 3 of authorisation or from your previous Access Token refresh.
scope optional The scope(s) required for your application, if different than from your first OAuth2 authorisation. Please be aware that no extra scopes can be granted past your current set of scopes.

Example

HTTP/1.1 POST https://v3.pebblepad.co.uk/login/OAuth2/TokenEndpoint
grant_type=refresh_token&refresh_token=n0b+qU.g3wZ-+W/5Ar+7t6D+_v/w0-qH

Response

access_token This is your Access Token to be used in requests to the API expires_in The time span in seconds in which the access_token is valid
token_type "bearer - the type of token granted - to be included in requests to the API
refresh_token This is your refresh token to be used when your Access Token has expired
scope The scope(s) granted to the client application
expires_in The duration in seconds that the token will be valid for

Example

{
 "access_token" : "D/5./y_Ck01935V9u.FaY~8n157k1-y_",
 "token_type" : "bearer",
 "expires_in" : 3600,
 "refresh_token" : "n0b+qU.g3wZ-+W/5Ar+7t6D+_v/w0-qH",
 "scope" : "default"
}

Error Responses

error The error string (see possible errors below)
state optional The value passed in as "state" in the Step 1

invalid_grant

The refresh token given is not valid.

unsupported_grant_type

The grant type requested is not "authorization_code" or "refresh_token" and is unsupported.

invalid_scope

The scope(s) given extend past the scopes currently granted to your application.

invalid_request

The request did not have all the required parameters, or a parameter was given that was not specified in the required or optional parameters.

Now you have a refreshed token you can make a valid call to the API. The following section describes how to send a form response. You will need the access token returned from the refresh, the username for the form response and also the data transfer object structure, use the example or contact our support team for help on this.

Using the API in PebblePad

Sending a form response

Use this endpoint to save a form response to the authorising user's Asset Store. NOTE: all calls using this method need to be sent as a multipart form.

Uri

/api/1.0/Form

Verb

POST

Headers

Authorization required This will be "Bearer" followed by a space and your Access Token
x-impersonateuser required The username of the user that the form response is to be recoreded against

Parameters

dto required This will be the JSON serialised Form Response Object (see below for Form Response's Data Transfer Object Structure)
email optional A Boolean value (true/false) to indicate whether to send an email if/when the save successfully completes of fails
digest optional A Boolean value (true/false) to indicate whether to add this event to the user's weekly digest (dependant on user's digest settings)

Data Transfer Object Structure

formId String The Id of the form to which the Form Response is for
title String Title for the Form Response
answers Object[] An object for each answer in the form
id String The Id of the form element for which the answer is for
values String[] The answer(s) for the form element. All answers should be transmitted using UTF-8 character encoding. The following HTML tags can be used where answers are in response to a text block field: <p>, <span>, <strong>, <ul>, <li>, <ol> <a>, <em>, <font>, <sub>, <sup>
created DateTime The Date and Time in which the Form Response was created
lastModified DateTime The Date and Time in which the Form Response was last changed
mainType String "FormResponse" - the main type for this asset
subtype String The sub type for this form response - should match the form's category;
"plan", "experience", "reflection", "talent", "worksheet", "feedback"

All fields are required

Date Transfer Object Structure Example

{
 "formId": "5388ffc7-4838-4f84-a5cc-122507729fbc",
 "title": "My title",
 "answers": [
 {
 "id": "826b9645-bcfe-47c9-969b-eccda0688985",
 "values": [ "My title" ]
 },
{
 "id": "826b9645-bcfe-47c9-969b-eccda0688986",
 "values": [ "My description" ]
 },
{
 "id": "826b9645-bcfe-47c9-969b-eccda0688987",
 "values": [ "My reflection" ]
 }
 ],
 "created": "2015-02-18T16:37:34.055Z",
 "lastModified": "2015-02-18T16:38:46.061Z",
 "mainType": "FormResponse",
 "subType": "Reflection"
}

Example

HTTP/1.1 POST https://v3.pebblepad.co.uk/api/1.0/Form
Authorization: Bearer D/5./y_Ck01935V9u.FaY~8n157k1-y_
x-impersonateuser: pat
email=true&digest=false&dto={"formId":"597G4M9bf8383xbHj5Wb5pWgbr",
                             "title":"My title",
                             "answers":[ {"id":"826b9645-bcfe-47c9-969beccda0688985", "values":["My title"]},
                                         {"id":"826b9645-bcfe-47c9-969beccda0688986", "values":["My description"]},
                                         {"id":"826b9645-bcfe-47c9-969beccda0688987","values":["My reflection"]}],
                             "created":"2015-02-18T16:37:34.055Z",
                             "lastModified":"2015-02-18T16:38:46.061Z",
                             "mainType":"FormResponse",
                             "subType":"Reflection"}

Response

HTTP/1.1 200 OK

Error Responses

400 Bad Request

This can be returned if the Form cannot be found with the Id provided, or the JSON for the Form Response DTO is malformed.

Getting started obtaining an Access Token via OAuth2 (Non service account approach)

Definitions

Client Id A case sensitive, special serialisation of letters and numbers identifying the client application.
Scope A permission or area of the API in which your application will be allowed / given access. The permissions and areas of access requested will be shown to the user during their authorising of your application.

You will need

  • Your client Id
  • Your chosen scope(s)
  • Your installation location

Available scopes

Custom scope definition is not supported in PebblePad earlier than release v.1.5.1.
Administrative scopes are available via creating a Service Account on the PebblePad Admin site. Each method is documented with the required scope for access.
The scopes currently available are:

  • admin_usermanagement:crud
  • formresponses:c

Each scope takes the format of [scopename]:[crudpermissions]. A method only requires a single permission, e.g. User/Get requires admin_usermanagement:r.

Step 1 - Authenticating the user and authorising the client application

For this step you will need to forward the user's browser to the below Uri with the necessary GET parameters.

Uri

/login/OAuth2/AuthorisationEndpoint

Verb

GET

Parameters

client_id required This will be your given Client Id
response_type required "code" - the type of OAuth2 Request
state optional This value will be passed to the redirect_uri after the user is authorised
scope optional The scope(s) required for your application
redirect_uri optional Must match the original Uri registered for the client application

Example

HTTP/1.1 GET
https://v3.pebblepad.co.uk/login/OAuth2/AuthorisationEndpoint
client_id=pebble_33a6e21fc0e142dda49a058c05357ffe&response_type=code

Response

None-REST; a web interface for the authorising user to authenticate and authorise your application.

Error Responses

OAuth2 Error Page
This error is shown when the Client Id or the redirect Uri given is invalid. This may also show if the authorising user takes longer than 2 minutes to authorise your application.

Step 2 - Receiving your Request Code

For this step the user will be redirected to your registered redirect Uri.

Uri

Your registered Uri

Verb

INBOUND GET

Response

code Your request code to be used in Step 3 - this code is only
valid for 2 minutes state optional The value passed in as "state" in the Step 1

Error Responses

error The error string (see possible errors below)
state optional The value passed in as "state" in the Step 1

unsupported_response_type
The response_type requested in Step 1 was something other than "code" and unsupported.

invalid_request
The request in Step 1 did not have all the required parameters, or a parameter was given that was not specified in the required or optional parameters.

access_denied
The user has selected Deny at the authorisation page, or attempted to authorise your application twice.

Step 3 - Receiving your Access Token and Refresh Token

This is where you obtain you final Access Token to be used when querying the API for the following hour, and additionally a refresh token to use when that Access Token has expired to obtain a new one (See section 'Refreshing your Access Token' for more information).

Uri

/login/OAuth2/TokenEndpoint

Verb

POST

Parameters

grant_type required "authorization_code" - the type of token request
code required This will be the code you received in Step 2
client_id required This will be your given Client Id
redirect_uri required
/optional
Must match the original Uri registered for the client application
Note: this parameter is required if it was supplied in Step 1

Example

HTTP/1.1 POST 
https://v3.pebblepad.co.uk/login/OAuth2/TokenEndpoint
grant_type=authorization_code&code=v8nZg*29IQ03_lG2+&client_id=pebble_33a6e21fc0e142dda49a058c05357ffe

Response

access_token This is your Access Token to be used in requests to the API
expires_in The time span in seconds in which the access_token is valid
token_type "bearer" - the type of token granted - to be included in requests to the API
refresh_token This is your refresh token to be used in Step 4 when your Access Token has expired
scope The scope(s) granted to the client application

Example

{
 "access_token" : "D/5./y_Ck01935V9u.FaY~8n157k1-y_",
 "token_type" : "bearer",
 "expires_in" : 3600,
 "refresh_token" : "n0b+qU.g3wZ-+W/5Ar+7t6D+_v/w0-qH",
 "scope" : "default"
}

Error Responses

error The error string (see possible errors below)
state optional The value passed in as "state" in the Step 1

invalid_grant

The code given is not valid, has already been used, or has expired past 2 minutes.

unsupported_grant_type

The grant type requested is not "authorization_code" or "refresh_token" and is unsupported.

invalid_client

The client Id given does not match the client Id for the code given, or the redirect Uri provided does not match the Uri given in Step 1.

invalid_request

The request did not have all the required parameters, or a parameter was given that was not specified in the required or optional parameters.

Troubleshooting

API Request Errors

The following describes the potential errors you may encounter from bad requests.

400 Bad Request

Check the format of the message and that all information explicitly required is correct.

401 Unauthorised

Check that you have correctly added the Access Token to the header in the format "Bearer {Token}", the Access Token has not expired and the scope given to the application allows access to the endpoint you are attempting to use. Additional JSON information for this error is given in the response body.

HTTP/1.1  400 { 
  "error":"invalid_token" 
}

Possible error values are:

invalid_token The Access Token given was not recognised as valid. Check the format of your Authorization header, and the correctness of the token given. Additionally, reauthorizing your application may resolve this error.
token_expired The Access Token used was valid but has expired, you will need to use your refresh token and request a new Access Token for further API requests.
no_scope The endpoint you are attempting to use is not allowed with your applications currently applied scope(s), ensure you are requesting the correct scopes for these endpoint during OAuth2.
no_login_response There was an issue at the server in contacting our authentication service, if you're consistently experience this error, please contact PebblePad support.

403 Forbidden

This error means that the Access Token was valid however the user that it is linked to could not be authenticated. This can happen if the user no longer exists in PebblePad, has expired, or has - or in a group or organisation with - their Access Policy set to Deny.

429 Too Many Requests

You have exceeded your usage limits.