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 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 sequence of characters identifying the client application. |
| Client Secret | A case sensitive sequence of characters serving as a password for the client application. If you have one of these, it must be used for Basic scheme authentication on some endpoints. This value should be treated like any password, stored securely, and only sent on requests which require it for authentication. |
| 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 client Secret (if you have one)
- 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 | optional (required if not using Basic authentication) | 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 |
Authentication
If you have been given a client Secret then you must authenticate with it on this endpoint. To set the correct Basic Authorization header, join your client Id and client Secret (in ASCII encoding) with a colon. Then base64 encode this combined string. Taking the example from the specification let your client Id and client Secret be "Aladdin" and "open sesame" respectively. Then you would base64 encode the ASCII string "Aladdin:open sesame" and then set the final Authorization header of "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" on your request.
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. |
Authentication
If you have been given a client Secret then you must authenticate with it on this endpoint. To set the correct Basic Authorization header, join your client Id and client Secret (in ASCII encoding) with a colon. Then base64 encode this combined string. Taking the example from the specification let your client Id and client Secret be "Aladdin" and "open sesame" respectively. Then you would base64 encode the ASCII string "Aladdin:open sesame" and then set the final Authorization header of "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" on your request.
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 |