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.
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/ |
| 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. |
TBC.
For this step you will need to forward the user's browser to the below Uri with the necessary GET parameters.
/login/OAuth2/AuthorisationEndpoint
GET
| 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 |
HTTP/1.1 GET
https://v3.pebblepad.co.uk/login/OAuth2/AuthorisationEndpoint?client_id=pebble_33a6e21fc0e142dda49a058c05357ffe&response_type=code
For this step the user will be redirected to your registered redirect Uri.
Your registered Uri
GET
| 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 | 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.
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).
/login/OAuth2/TokenEndpoint
POST
| 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 |
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.
HTTP/1.1 POST
https://v3.pebblepad.co.uk/login/OAuth2/TokenEndpoint
grant_type=authorization_code&code=v8nZg*29IQ03_lG2+&client_id=pebble_33a6e21fc0e142dda49a058c05357ffe
| 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 |
{
"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 | 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.
This is where you obtain you another Access Token should you need to - using your previously given Refresh Token.
/login/OAuth2/TokenEndpoint
POST
| 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. |
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.
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
The response is the same as the example in "Step 3 - Receiving your Access Token and Refresh Token"
| 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.
As documented in the API Version pages.
As documented in the API Version pages.
| 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!) |
As documented in the API Version pages.
As documented in the API Version pages.
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).
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 |
Provides the methods for interacting with user records. Each record has a unique Id that is maintained internally by PebblePad's systems. This is not configurable. In every record type, it is the "Id" Guid field, and will be described as "PebblePad's xxxx Id", or similar. There is another field: "CustomId". This is a string in all records. You can use this to match records in PebblePad to those in your own systems. This field will normally be described as "Your Custom Id" or similar.
| API | Description |
|---|---|
| POST 1.5/User/MakeAlumni |
Make alumni account for user (please note this endpoint does not check if an alumni request email has already been sent so we advise not calling this endpoint frequently, it will prevent the sending of further emails for users who complete the alumni signup process though) |
| POST 1.5/User/SetDormant |
Set user accounts as dormant |
| POST 1.5/User/UnsetDormant |
Unset user accounts as dormant |
| POST 1.5/User/Restore |
Restore users accounts |