Getting Started

Introduction

The PebblePad API is a HTTPS API using OAuth2 authentication. We suggest that you try out tools such as the Postman - API Client (Packaged App) when first using a HTTPS 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 you directly with the "Access Token" that has the necessary scopes.

Every call to the API, requires the use of an Access Token, the documentation leads you through the two methods starting with the manual authentication approach and describing Service Accounts further on.

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/
Canada https://pebblepad.ca/login/OAuth2/
https://pebblepad.ca/api/
TAQAS (Testing) https://v3test.pebblepad.com/login/OAuth2/
https://v3test.pebblepad.com/api/

Getting started obtaining an Access Token via OAuth2

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

Scopes

TBC.

Request Process

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

Http Method

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
The user will be shown 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 Authorization Code

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

Uri

Your registered Uri

Http Method

GET

Response
code required 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 Step 1
Error Responses
error required The error string (see possible errors below)
state optional The value passed in as "state" in Step 1

unsupported_request_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

Http Method

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 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 required 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.

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 (the below section is on Refresh Tokens).

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

Http Method

POST

Parameters
grant_type required "refresh_token" - the type of token request
refresh_token required This will be the refresh_token you received in Step 3 of authorisation, from your previous Access Token refresh, or directly from Support for Service Accounts.
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 originally requested 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

The response is the same as the example in "Step 3 - Receiving your Access Token and Refresh Token"

Error Responses
error required 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.

Making a Request to the PebblePad API

Uri

As documented in the API Version pages.

Http Method

As documented in the API Version pages.

Headers
Authorization required This will be "Bearer" followed by a space and your Access Token (e.g. Bearer jdhfjksdhf67w65789/.,.wwdf)
X-ImpersonateUser optional The username of the User to impersonate for this request (may not be operational for all endpoints!)
Parameters

As documented in the API Version pages.

Response

As documented in the API Version pages.

Error Responses

These responses are global responses from the API, but each endpoint has a much more detailed set of error responses corresponding to it's own actions.

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.

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 (see below section).

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 hit the endpoint Uri: 1.1/Info/GetRateLimits (no authentication required) to see the current rate limits across the PebblePad API.

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