One time Authentication for Public Resource
Hi there,
The current authentication mechanism is heavy for public image resources. When you retrieve a page content with authenticated token, the image URLs that are referenced still need to have OAuth token added whenever you request them. We heard people from UserVoice Forums want OneNote APIs support preAuthenticated image URLs from a OneNote page that a browser can GET. This new API feature is available now!
Once the user has sent an authenticated Page Content Resource request with parameter "preAuthenticated" set to true, it allows browser to fetch the image resource without authentications for a limited time. Its response will contain the public resource URL in a format that shows the resource is a public resource and its content type accordingly. This public resource URL will be available for 1 hour without the need for additional authentication!
How can you trigger this feature? Follow these steps:
1. Get the ID of the page with image resources.
2. Send GET page content request with preAuthenticated parameter, for example:
GET https://www.onenote.com/api/v1.0/me/notes/pages/{pageId}/content?preAuthenticated=true
3. A response with 200 means it is a successful return. And you can find a resource URL link looks like this:
https://www.onenote.com/api/v1.0/me/notes/resources/{resourceId}/content?publicAuth=true&mimeType=image/jpeg
4. The response contains headers with expire UTC datetime and content type of the resource:
X-ResourceExpires: 3/21/2016 11:08:27 PM
Content-Type: image/gif
5. Now this resource URL is available for 1 hour without the need for additional authentication.
Supported Scenarios:
• Windows Live Account
• Office365 Account with Me/Users/Group/Site scenarios
Remarks:
The UTC datetime info in header "X-ResourceExpire" shows the exact datetime that the URL is going to expire. Please note that the datetime is set in the header when you request the resource. The actual expire time could be changed if you send the Page Content Resource request with "preAuthenticated=true" again, which will refresh the expiration time with another one hour extension. So you could get different datetime for different resource requests, if you have multiple Page Content Resource calls on the same page in between. The actual expiration time will be the latest one.
Examples:
• Page Content Resource request:
GET https://www.onenote.com/api/v1.0/me/notes/pages/{pageId}/content?preAuthenticated=true
• Page Content Resource response:
img alt="Rainier.gif" width="279" height="236" src="https://www.onenote.com/api/v1.0/me/notes/resources/{resourceId}/content?publicAuth=true&mimeType=image/gif" data-src-type="image/gif" data-fullres-src="https://www.onenote.com/api/v1.0/me/notes/resources/{resourceId}/content?publicAuth=true&mimeType=image/gif" data-fullres-src-type="image/gif"
• Preauthenticated Resource Retrieval request:
GET https://www.onenote.com/api/v1.0/me/notes/resources/{resourceId}/content?publicAuth=true\&mimeType=image/jpeg
• Preauthenticated Resource Retrieval response:
X-ResourceExpires: 3/21/2016 11:08:27 PM
Content-Type: image/gif
References:
• Get page content request: https://dev.onenote.com/docs#/reference/get-pages/v10menotespagesidcontentincludeids
• Construct the request URI for Me/Users/Group/Site scenario: https://msdn.microsoft.com/office/office365/howto/onenote-get-content#request-uri
• Add images and files to OneNote pages: https://msdn.microsoft.com/en-us/office/office365/howto/onenote-images-files
Let us know what you think on UserVoice, contact us on twitter @onenotedev, or ask questions tagged onenote on Stack Overflow
Have fun,
Linda