- Article
Use Microsoft Graph
This topic contains information about authorizing an application using Microsoft accounts for OneDrive personal.However, this approach is no longer recommended.New applications should be developed using Microsoft Graph and follow the authorization process in Authorization and sign-in for OneDrive in Microsoft Graph.
Getting started
To use the OneDrive API, you need to have an access token that authenticatesyour app to a particular set of permissions for a user. In this section, you'll learn how to:
- Register your application to get a client ID and a client secret.
- Sign your user in to OneDrive with the specified scopes using the token flow or code flow.
- Sign the user out (optional).
The OneDrive API uses the standard OAuth 2.0 authentication scheme to authenticate users and generate access tokens. You must provide an access token for every API call via one of the following.
- An HTTP header:
Authorization: bearer {token}
Register your app
To authenticate your app, you need to register your app with Microsoft and provide some details aboutyour app.
To register your app
See the topic on registering your app for OneDrive APIfor details on how to register your app.
Sign users in
Your app must initiate the sign-in process by contacting theMicrosoft account authorization web service with a specified scope, and receivean access token. The flow follows standard OAuth 2.0 authentication flows andrequires calls from a web browser or web-browser control.
Authentication scopes
Scopes determine what type of access the app is granted when the user is signedin. All scopes support single sign-on on the web, which means that if a user isalready signed in to OneDrive, then the user can skip the authentication flowand go straight to the authorization flow.
| Scope name | Description | Required |
|---|---|---|
| offline_access | Enables your app to work offline even when the user isn't active. This provides your app with a refresh_token that can be used to generate additional access tokens as necessary. This scope is not available for token flow. | No |
| onedrive.readonly | Grants read-only permission to all of a user's OneDrive files, including files shared with the user. | Yes |
| onedrive.readwrite | Grants read and write permission to all of a user's OneDrive files, including files shared with the user. To create sharing links, this scope is required. | Yes |
| onedrive.appfolder | Grants read and write permissions to a specific folder for your application. | Yes |
As an example, a typical application might request the following scopes:
onedrive.readwrite offline_accessSupported Authentication flows
There are two supported authentication flows to choose from:
- Token flow
- Code flow
Token flow
The easiest authentication flow is the token flow. This flow is useful for quicklyobtaining an access token to use the OneDrive API in an interactive fashion. This flowdoes not provide a refresh token, so it can't be used for long term access to theOneDrive API.
To start the sign-in process with the token flow, use a web browser or web-browsercontrol to load a URL request.
GET https://login.live.com/oauth20_authorize.srf?client_id={client_id}&scope={scope} &response_type=token&redirect_uri={redirect_uri}Required query string parameters
| Parameter name | Value | Description |
|---|---|---|
| client_id | string | The client ID value created for your application. |
| redirect_uri | string | The redirect URL that the browser is sent to when authentication is complete. |
| response_type | string | The type of response expected from the authorization flow. For this flow, the value must be token. |
| scope | string | A space-separated list of scopes your application requires. |
Use this redirect URL for mobile and desktop applications https://login.live.com/oauth20_desktop.srf.
Response
Upon successful authentication and authorization of your application, the web browserwill be redirected to your redirect URL with additional parameters added to the URL.
https://login.live.com/oauth20_authorize.srf#access_token=EwC...EB &authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600 &scope=onedrive.readwrite&user_id=3626...1dValues for access_token, authentication_token, and user_id are truncatedin the previous example. The values for access_token and authentication_tokenare quite long.
You can use the value of access_token to make requests to the OneDrive API.
Code flow
The code flow for authentication is a three-step process with separate calls to authenticate and authorizethe application and to generate an access token to use the OneDrive API. This alsoallows your application to receive a refresh token that will enable long-termuse of the API in some scenarios, to allow access when the user isn't actively using your application.
Step 1. Get an authorization code
To start the sign-in process with the code flow, use a web browser or web-browsercontrol to load this URL request.
GET https://login.live.com/oauth20_authorize.srf?client_id={client_id}&scope={scope} &response_type=code&redirect_uri={redirect_uri}Required query string parameters
| Parameter name | Value | Description |
|---|---|---|
| client_id | string | The client ID created for your app. |
| scope | string | A space-separated list of scopes that your app requires. |
| redirect_uri | string | The redirect URL that the browser is sent to when authentication is complete. |
| response_type | string | The type of response expected from the authorization flow. For this flow, the value must be code. |
Response
Upon successful authentication and authorization of your application, the web browserwill be redirected to your redirect URL with additional parameters added to the URL.
https://login.live.com/oauth20_authorize.srf?code=df6aa589-1080-b241-b410-c4dff65dbf7cStep 2. Redeem the code for access tokens
After you have received the code value, you can redeem this code for a set oftokens that allow you to authenticate with the OneDrive API. To redeem the code, make the following request:
POST https://login.live.com/oauth20_token.srfContent-Type: application/x-www-form-urlencodedclient_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}&code={code}&grant_type=authorization_codeRequired request body parameters
The request body is a properly encoded URL string, with some required parameters.
| Parameter name | Value | Description |
|---|---|---|
| client_id | string | The client ID value created for your application. |
| redirect_uri | string | The redirect URL that the browser is sent to when authentication is complete. This should match the redirect_uri in the first request. |
| client_secret | string | The client secret created for your application. |
| code | string | The authorization code you received in the first authentication request. |
Note For web apps, the domain portion of the redirect URI must match thedomain portion of the redirect URI that you specified in theMicrosoft account Developer Center.
Response
If the call is successful, the response for the POST request contains a JSON stringthat includes several properties, including access_token, token_type, andrefresh_token (if you requested the wl.offline_access scope).
{ "token_type":"bearer", "expires_in": 3600, "scope":"wl.basic onedrive.readwrite", "access_token":"EwCo...AA==", "refresh_token":"eyJh...9323"}You can now store and use the access_token provided to make authenticatedrequests to the OneDrive API.
Important: Treat the values of access_token and refresh_token in this response as securely as you would a user's password.
The access token is valid for only the number of seconds that isspecified in the expires_in property. You can request a new access tokenby using the refresh token (if available), or by repeating the authenticationrequest from the beginning.
Step 3. Get a new access token or refresh token
If your app has requested access to wl.offline_access this step willreturn a refresh_token that can be used to generate additional accesstokens after the initial token has expired.
To redeem the refresh token for a new access token, make the following request:
POST https://login.live.com/oauth20_token.srfContent-Type: application/x-www-form-urlencodedclient_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}&refresh_token={refresh_token}&grant_type=refresh_tokenRequired request body parameters
The request body is a properly encoded URL string, with some required parameters.
| Parameter name | Value | Description |
|---|---|---|
| client_id | string | The client ID created for your application. |
| redirect_uri | string | The redirect URL that the browser is sent to when authentication is complete. This should match the redirect_uri value used in the first request. |
| client_secret | string | The client secret created for your application. |
| refresh_token | string | The refresh token you received previously. |
Note For web apps, the domain portion of the redirect URI must match thedomain portion of the redirect URI that you specified in theLive SDK app management site.
Response
If the call is successful, the response for the POST request contains a JSON stringthat includes several properties including access_token, authentication_token andrefresh_token if you requested the wl.offline_access scope.
{ "token_type":"bearer", "expires_in": 3600, "scope": "wl.basic onedrive.readwrite wl.offline_access", "access_token":"EwCo...AA==", "refresh_token":"eyJh...9323"}You can now store and use the access_token to make authenticatedrequests to the OneDrive API.
Important: Treat the values of access_token and refresh_token in thisresponse as securely as you would a user's password.
The access token is valid for only the number of seconds that isspecified in the expires_in property. You can request a new access tokenby using the refresh token (if available) or by repeating the authenticationrequest from the beginning.
Sign the user out
To sign a user out, perform the following steps:
- Delete any cached
access_tokenorrefresh_tokenvalues you've previouslyreceived from the OAuth flow. - Perform any sign out actions in your application (for example, cleaning up local state,removing any cached items, etc.).
- Make a call to the authorization web service using this URL:
GET https://login.live.com/oauth20_logout.srf?client_id={client_id}&redirect_uri={redirect_uri}This call will remove any cookies that enable single sign-on to occur and ensurethat next time your app launches the sign in experience, the user will be requested toenter a username and password to continue.
Required query string parameters
| Parameter name | Value | Description |
|---|---|---|
| client_id | string | The client ID value created for your application. |
| redirect_uri | string | The redirect URL that the browser is sent to when authentication is complete. This must match exactly the redirect_uri value used in the get token request. |
After removing the cookie, the browser will be redirected to the redirect URLyou provided. When the browser loads your redirect page, no authentication querystring parameters will be set, and you can infer the user has been logged out.
Revoking Access
Users can revoke an app's access to their account by visiting theMicrosoft account manage consent page.
When consent for your app is revoked, any refresh token previously provided to your applicationwill no longer be valid. You will need to repeat the authentication flow torequest a new access and refresh token from scratch.
Errors
If there are errors with authentication, the web browser will be redirected toan error page. While the error page always presents an end-user friendly messagethe URL for the error page includes additional information that may help youdebug what happened. This information is not always shown in the content of theerror page displayed in the browser.
https://login.live.com/err.srf?lc=1033#error={error_code}&error_description={message}The URL includes query parameters that you can use to parse the error and respondaccordingly. These parameters are always included as a bookmark (after the #character). The page content will always display a generic error message forthe user.
If the user selects not to provide consent to your application, the flow willredirect to your redirect_uri and include the same error parameters.
Error parameters
| Parameter name | Value | Description |
|---|---|---|
| error | string | Error code identifying the error that occurred. |
| error_description | string | A description of the error. |
The following topics contain high-level overviews of other concepts that applyto the OneDrive API.
- Develop with the OneDrive API
