Authentication Endpoint


Nomenclature

  • Client: the client application which is sending the calls to the ipushpull service.

  • User: the human user of the client application.

  • client_id: a unique alphanumeric code identifying the client application. ipushpull will provide this during onboarding.

  • client_secret: a sort-of password (alphanumeric) known to the client application and web service. ipushpull will provide this during onboarding.

  • username: the User's email address.

  • password: the User's password.

  • access_token: a time-limited token granting the user access to the site for a limited period.

  • refresh_token: a token that the Client application can use to request new access_tokens.

 

Authentication Endpoint

ipushpull uses the OAuth 2.0 password grant protocol for authentication.

When authenticating, the client should send a POST request to the following endpoint:

1 /api/1.0/oauth/token/

The following information needs to be included in the POST message:

  • Headers

    • Authorization: Basic {Base64 Encoded ClientID:ClientSecret}
      Note: The Client ID and Client Secret need to be sent with a colon between them and Base 64 encoded.

    • Content-Type: application/x-www-form-urlencoded

  • Body

    • grant_type=password&username={USERNAME}&password={PASSWORD}

If successful, the server returns a status of 200 and the following data:

1 2 3 4 5 6 7 { "access_token": "9vJ6YxYU10tLhAZTIRudztrnU3gnQv", "expires_in": 86400, "token_type": "Bearer", "scope": "read write", "refresh_token": " ziUmQDJ3lizwqtLy5aTzWIgzN6ucZz" }


If unsuccessful, the server returns a HTTP error status e.g. 401 and the cause of the error in json format. The content varies depending on error e.g. this is what you get if username/password don't match:

1 2 3 4 5 { "error": "invalid_grant", "error_description": "Invalid username or password.", "warning": "You have 9 attempt(s) remaining" }
cURL Example
1 2 3 4 curl --location --request POST 'https://test.ipushpull.com/api/1.0/oauth/token/' \ --header 'Authorization: Basic ZHZYb1hvVkdNRERidGd5a3lSOXVMml0NDdrVElTMEFPVjpVNm8wZEVsWlFSdlRLYVRVdDVRT05KVU8wV0RUWEZkTFU5SGVCOXpFaXZ2QjQxdFZOdFZsRWtWZ2J0VzI2Wmp1nV3lwRXlOUzE4dHRjeUpYVjVVT2JZeGRTR2tKTFpKZFdLVUNJa1JKT3Q5SzZnQnJENk9ZZDNLSkx6Qw==' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-raw 'grant_type=password&username=joe.bloggs@company.com&password=Password123'
Python Example using Requests
1 2 3 4 5 6 7 8 9 import requests url = "https://test.ipushpull.com/api/1.0/oauth/token/" payload = "grant_type=password& username=joe.bloggs@company.com&password=Password123" headers = { 'Authorization': 'Basic ZHZYb1hvVkdNRERidGd5a3lSOXVMml0NDdrVElTMEFPVjpVNm8wZEVsWlFSdlRLYVRVdDVRT05KVU8wV0RUWEZkTFU5SGVCOXpFaXZ2QjQxdFZOdFZsRWtWZ2J0VzI2Wmp1nV3lwRXlOUzE4dHRjeUpYVjVVT2JZeGRTR2tKTFpKZFdLVUNJa1JKT3Q5SzZnQnJENk9ZZDNLSkx6Qw==', 'Content-Type': 'application/x-www-form-urlencoded' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)



Refreshing Access Token

The access token will expire after 24 hours. If you make a request after the token has expired, the service will return a status of 401 (Unauthenticated) and the following response:

1 2 3 { "detail": "Authentication credentials were not provided." }


When you receive an unauthenticated status, request a new access_token by sending a POST request containing the refresh_token you were sent when you first authenticated in the body of the message. Send the request to the same URL as previously used but this time the Body should contain the refresh_token:

1 grant_type=refresh_token&refresh_token=ziUmQDJ3lizwqtLy5aTzWIgzN6ucZz


If successful, this will return a status of 200 and a response containing a new access_token and a new refresh_token:

1 2 3 4 5 6 7 { "access_token": "2hmLuPirUkcKQZOQDK9Y2AfKFDhD3j", "expires_in": 86400, "token_type": "Bearer", "scope": "read write", "refresh_token": "SgmdShiCcRu0kVxUPocqARDcWrljAG" }


The previous access_token and refresh_token should be discarded and the new ones used until the access_token expires again. Note that refresh_tokens are single use – once used they are invalidated and cannot be used again.
If the refresh_token request fails, the web service will return a status of 401 and the following content:

1 2 3 4 { "error": "invalid_grant", "error_description": "Invalid username or password." }

If this situation occurs then you should force the user to re-enter their username and password.

cURL Example
1 2 3 4 curl --location --request POST 'https://test.ipushpull.com/api/1.0/oauth/token/' \ --header 'Authorization: Basic ZHZYb1hvVkdNRERidGd5a3lSOXVMml0NDdrVElTMEFPVjpVNm8wZEVsWlFSdlRLYVRVdDVRT05KVU8wV0RUWEZkTFU5SGVCOXpFaXZ2QjQxdFZOdFZsRWtWZ2J0VzI2Wmp1nV3lwRXlOUzE4dHRjeUpYVjVVT2JZeGRTR2tKTFpKZFdLVUNJa1JKT3Q5SzZnQnJENk9ZZDNLSkx6Qw==' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-raw 'grant_type=refresh_token&refresh_token=ziUmQDJ3lizwqtLy5aTzWIgzN6ucZz'
Python Example using Requests
1 2 3 4 5 6 7 8 9 10 11 12 13 import requests url = "https://test.ipushpull.com/api/1.0/oauth/token/" payload = "grant_type=refresh_token&refresh_token=ziUmQDJ3lizwqtLy5aTzWIgzN6ucZz" headers = { 'Authorization': 'Basic ZHZYb1hvVkdNRERidGd5a3lSOXVMml0NDdrVElTMEFPVjpVNm8wZEVsWlFSdlRLYVRVdDVRT05KVU8wV0RUWEZkTFU5SGVCOXpFaXZ2QjQxdFZOdFZsRWtWZ2J0VzI2Wmp1nV3lwRXlOUzE4dHRjeUpYVjVVT2JZeGRTR2tKTFpKZFdLVUNJa1JKT3Q5SzZnQnJENk9ZZDNLSkx6Qw==', 'Content-Type': 'application/x-www-form-urlencoded' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)

How to use your access token to authenticate requests

Once you have a valid access token you can use it to authenticate your pushes by including it in the header of your requests. Your headers should look like this:

1 "Authorization: Bearer <access_token>"

Example curl syntax:

1 2 curl --location --request GET 'https://test.ipushpull.com/api/2.0/domains/id/1/page_content/id/1/' \ --header 'Authorization: Bearer 2hmLuPirUkcKQZOQDK9Y2AfKFDhD3j'