Postman is very important tool for developers to test APIs. It’s very useful in SPO since there are a lot of REST API that we can consume in many client applications to set and get data. Postman is providing a great help to test and validate the expected output from sending request to REST API. Moreover, it gives a friendly URL to setup the client call and identify which parameter to use and which headers are important.
How to Authorize Postman to SPO
Register a new app
Go to https://<YourSharePointCollectionURL>/_layouts/15/appregnew.aspx to register a new SharePoint app. Generate ClientID & Client Secret and add a title as in image 1
App domain is your tenant domain and Redirect URL is the site collection and I used https://<tenantURL>/sites/DeveloperSite/
After creation, you will be directed to a page that will show all the associated data to the app. You will need to copy these data especially the client secret. Note: you can’t retrieve the secret. image(2)
Grant the permission
This step is about to authorize this app y setting it’s scope and permission level as in table 1
| Permission level | Register URL |
| <AppPermissionRequests AllowAppOnlyPolicy=”true”> <AppPermissionRequest Scope=”http://sharepoint/content/sitecollection/web” Right=”FullControl” /> </AppPermissionRequests> | https://<sitecollection URL>/_layouts/15/appinv.aspx |
<AppPermissionRequests AllowAppOnlyPolicy="true"><AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" /></AppPermissionRequests> | https://<Tenant URL>/_layouts/15/appinv.aspx |
So, now we have client ID & secret and it’s granted to full read. Also, we have the tenant ID and if you don’t know the tenantID just navigate to /_layouts/15/appprincipals.aspx?Scope=Web under your web site and check the trusted apps. The GUID after the @ symbol is the tenant ID. image-3
Postman configuration:
You will need two request, the first is POST request to obtain the token and the second is GET request to get the results of the API.
POST request setup:
URL for this request https://accounts.accesscontrol.windows.net/tenantID/tokens/OAuth/2/
Request parameter will be added to the body of the request
| grant_type | client_credentials |
| client_id | clientID@tenantID |
| client_secret | The generated secret of the app |
| resource | 00000003-0000-0ff1-ce00-000000000000/YourSPODomainName@tenantID |
So, your setup should match image 4
The results should look like image 5 and the result of the request contains the access token to be used in the coming requests
Get request using API:
Let’s test with very simple API to retrieve the title of web site so the request URL should be https://we site URL/_api/web?$select=Title The parameters should be sent in the request header this time and you will need only parameters
| Authorization | Bearer access_token which was generated from authorization step |
| Content-Type | application/json;odata=verbose |
| Accept | application/json;odata=verbose |
The result should look like image 6
Common error:
Common error you can receive:
- AudienceUriValidationFailedException –> this means that the used domain in the resource is not correct. So, make sure that you used the correct name in the post request.
- Token type is not allowed –> you will need to enable this from SPO management shell by using
set-spotenant -DisableCustomAppAuthentication $false.
Resources:
- https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/register-sharepoint-add-ins?redirectedfrom=MSDN
- https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
- https://learn.microsoft.com/en-us/answers/questions/764631/getting-exception-of-type-microsoft-identitymodel
- https://learn.microsoft.com/en-us/answers/questions/714147/token-type-is-not-allowed-error-on-sharepoint-rest