Sharepoint Online Authentication for API Access using POSTMAN

Objective: We know most of the collaboration part of sharepoint has been pushed to Teams, with its planner, conversations, a dedicated site for document uploads and many other features.
So the sharepoint site is now used mostly for document management. Being said that how we can accomodate SPO API for other applications.

In this post we will use SP Online OOTB API to upload and download a file. We dont need to write a seperate application for this, instead we will use POSTMAN to interpret the calls.

When API is avilable OOTB why do we need this post?
Well Service API is available OOTB, but there is specific way we need to authenticate to use that API. That is what we are going to show here.

Let me give a highlevel overview of how authentication works in Office365 Sharepoint site in this case.

Step 1: Know your Tenant ID and Resource ID
It is very important to know your tenant ID for triggering any kind of service calls.
You can get your the Tenant ID in following ways:
1. Using Powershell
2. Making a call to "_vti_bin/client.svc"
3. This is the most easiest way browse "/_layouts/15/appprincipals.aspx"

We use 3rd way as it is the easiest way. When you browse that url under any SP Online site from your tenant. The part after "@" is your tenant ID and the part before @ is Resource ID. Make a note of it.

Step 2: Register a new app
You need to register a new addin/app in your Sharepoint site, this will generate a ClientID and a Client Secret, which we will use to authenticate. Lets see how to do it.

Go to "_layouts/15/appregnew.aspx" under the SP Online site which you want to use as document repository.

Use the "Generate" buttons to generate a unique ClientID and Client Secret. Give appropriate title to your app. You can make localhost as your domain name and redirect url.  Click Create.

Note: Please copy and paste those ClientID and Client Secret in a sepearte notepad file as you cannot retrieve them after saving this information.

Step 3: Grant permissions
New Client app has been created in SP Online site, now its time to decide what permissions this app should have on your site.  You can grant Site collection, web or even at list level read or write permissions.

Go to "/_layouts/15/appinv.aspx" and serach with ClientID we generated earlier. The application will fetch all other details based on your ClientID.

 Add the below XML snippet specifying what kind of permissions you want this app to have on your site.  I want to upload a document so i granted "Write" permission.

<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="Write" />
</AppPermissionRequests>

More details about the permissions are here.

Click "Create" button and you will be prompted if you trust the app to run with said permissions. Click Trust.

Note: App registration can also be done using Azure App services. But it requires a storage account and proper azure subscription and you need to pay for maintiaining app service in azure.
So we choose the cheap and easiest way.

Step 4: Get Access Token for the Office365 Tenant.
Open Postman and make a request for access token as below.

Header: 
Content-Type : application/x-www-form-urlencoded
Body:
grant_type : client_credentials
client_id : ClientID@TenantID
client_secret : Client Secret
resource: ResourceID/<TenantName>.sharepoint.com@TenantID

ResourceID is common for all of SPO.
Now click send and you will receive an access token.
Copy that access token as we need to send it in headers for every API request.
Please note that every access token will be valid for 3600 seconds or 1 hour.

Step 5: Make a call to Sharepoint REST API
Its time to test the access to REST API using the OAuth access token.

First we will make a call to get the title of the site using REST API. Below is the url we need to make a call to get Title.
https://1yearsub.sharepoint.com/sites/DEV/_api/web?$select=Title

Make a postman request shown as below with below headers.

Header:
Accept : application/json;odata=verbose
Authorization : Bearer <Access Token>

We see the title fetched by a REST API call using POSTMAN.

Upload Document Using REST API:
Headers will be same as above and it will be a POST call this time. Attach the file in the body tab of the POSTMAN call.

Header:
Accept : application/json;odata=verbose
Authorization : Bearer <Access Token>

REST Request Url : https://1yearsub.sharepoint.com/sites/DEV/_api/web/GetFolderByServerRelativeUrl('/sites/dev/shared documents')/Files/add(url='testfile.pdf',overwrite=true)

Here is the result:

Download the Document using REST API:
Headers will be same as above and its a Get call now.

Header:
Accept : application/json;odata=verbose
Authorization : Bearer <Access Token>

REST Request Url: https://1yearsub.sharepoint.com/sites/DEV/_api/web/GetFolderByServerRelativeUrl('/sites/dev/shared documents')/Files('testfile.pdf')/$value

Looking at the response we see that the file is downloaded in binary.

Hope this post gave some better idea on Accessing REST API of Sharepoint Online site.

Happy Coding !