Authorize access to REST APIs with OAuth 2.0

Last Update: 3/6/2017

Authenticate your web app's users to access the REST APIs so that your app doesn't have to keep asking for their usernames and passwords. Visual Studio Team Services uses the OAuth 2.0 protocol to authorize your app for a user and generate an access token. Use this token when you call the REST APIs from your app.

First, you'll register your web app and get an app ID from Visual Studio Team Services. Using that app ID, you'll send your users to Visual Studio Team Services to authorize your app to access their accounts there. Once they've done that, you'll use that authorization to get an access token for that user. When you call Visual Studio Team Services APIs on behalf of that user, you'll use that user's access token. Access tokens expire, so you'll also need to refresh the access token if it's expired.

Process to get authorization

Register your app

Go to (https://app.vssps.visualstudio.com/app/register) to register your app.

Make sure you select the scopes that your application needs, and then use the exact same scopes when you authorize your app. If you registered your app using the preview APIs, you'll want to re-register because the scopes that you used are now deprecated.

When Visual Studio Team Services presents the authorization approval page to your user, it will use your company name, and app name and descriptions, along with the URLs for your company's web site, your app's website, and your terms of service and privacy statements, like this.

Visaul Studio Online authorization page with your company and app information

When you call Visual Studio Team Services to ask for a user's authorization, and the user grants it, Visual Studio Team Services will redirect the user's browser to your authorization callback URL with the authorization code for that authorization. The callback URL must be a secure connection (https) to transfer the code back to the app. It must exactly match the URL registered in your app. If it doesn't, a 400 error page is displayed instead of a page asking the user to grant authorization to your app.

When your register your app, the application settings page is displayed.

Application settings for your app

You'll call the authorization URL and pass your app ID and authorized scopes when you want to have a user authorize your app to access his Visual Studio Team Services account. You'll call the access token URL when you want to get an access token to call a Visual Studio Team Services REST API.

The settings for each app that you register are available from your profile (https://app.vssps.visualstudio.com/profile/view).

Authorize your app

If your user hasn't yet authorized your app to access his Visual Studio Team Services account, call the authorization URL.

GET https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id={app ID}
        &response_type=Assertion
        &state={state}
        &scope={scope}
        &redirect_uri={callback URL}
Parameter Type Notes
client_id GUID The ID that was assigned to your app when you registered it.
response_type string Assertion
state string Typically a generated value that correlates the callback with its associated authorization request.
scope string Scopes register with your app. Space separated. See available scopes.
redirect_uri URL Your app's URL to call back with the authorization code and response token.

Visual Studio Team Services will ask your user to authorize your app. It will handle authentication and then call you back with an authorization code, if the user approves the authorization.

For example, when you call the authorization URL like this:

GET https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id=88e2dd5f-4e34-45c6-a75d-524eb2a0399e
        &response_type=Assertion
        &state=User1
        &scope=vso.work%20vso.code_write
        &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback

Visual Studio Team Services ask the user to authorize your app and then call your app like this:

GET https://fabrikam.azurewebsites.net/myapp/oauth-callback
        ?code={authorization code}
        &state=User1

Get an access token

When you get the authorization code, use it to get an access token and a refresh token.

POST https://app.vssps.visualstudio.com/oauth2/token
        ?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        &client_assertion={AppSecret}
        &grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
        &assertion={authorization code}
        &redirect_uri={callbackUrl}
Content-type: application/x-www-form-urlencoded
Parameter Type Value
client_assertion_type string urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion string Your app's app secret.
Assigned when you register your app and available in your profile.
grant_type string urn:ietf:params:oauth:grant-type:jwt-bearer
assertion string Your user's authorization code.
Returned to your app's callback when you called the authorization URL, if the user authorized your app.
redirect_uri URL You're app's callback.

Response

{
    "access_token": { access token for this user },
    "token_type": { type of token },
    "expires_in": { Time in seconds that the token remains valid },
    "refresh_token": { Refresh token to use when the token has timed out }
}

Store this data so you don't have to authorize this user for the app for each session.

Use the access token

Send the access token as a header when you call a Visual Studio Team Services REST API.

Authorization: Bearer {access_token}

For example, here's how to use the authoziation token to get all the builds for the Visual Studio account.

GET https://{account}.VisualStudio.com/DefaultCollection/_apis/build/builds
Authorization: Bearer {access_token}

Refresh an expired access token

If an access token is expired, use the refresh token to get a new one.

POST https://app.vssps.visualstudio.com/oauth2/token
        ?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        &client_assertion={AppSecret}
        &grant_type=refresh_token
        &assertion={refresh token}
        &redirect_uri={callbackUrl}
Content-type: application/x-www-form-urlencoded
Parameter Type Value
client_assertion_type string urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion string Your app's app secret.
Assigned when you register your app and available in your profile.
grant_type string refresh_token
assertion string Your user's refresh token.
Returned when you got the access token.
redirect_uri URL You're app's callback.

Response

{
    "access_token": { access token for this user },
    "token_type": { type of token },
    "expires_in": { Time in seconds that the token remains valid },
    "refresh_token": { Refresh token to use when the token has timed out }
}

Scopes

IMPORTANT: Scopes only enable access to REST APIs and select Git endpoints. SOAP API access is not supported.

Scope Name Description Included by
vso.agentpools_manage Agent Pools (read, manage) Grants the ability to manage pools, queues, and agents
vso.agentpools Agent Pools (read) Grants the ability to view tasks, pools, queues, agents, and currently running or recently completed jobs for agents vso.agentpools_manage
vso.build Build (read) Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to receive notifications about build events via service hooks. vso.build_execute
vso.build_execute Build (read and execute) Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to queue a build, update build properties, and the ability to receive notifications about build events via service hooks.
vso.chat_write Team rooms (read and write) Grants the ability to access rooms and view, post, and update messages. Also grants the ability to receive notifications about new messages via service hooks. vso.chat_manage
vso.chat_manage Team rooms (read, write, and manage) Grants the ability to access rooms and view, post, and update messages. Also grants the ability to manage rooms and users and to receive notifications about new messages via service hooks.
vso.code Code (read) Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to get notified about version control events via service hooks. vso.code_write
vso.code_manage
vso.code_write Code (read and write) Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage pull requests and code reviews and to receive notifications about version control events via service hooks. vso.code_manage
vso.code_status Code (status) Grants the ability to read and write commit and pull request status.
vso.code_manage Code (read, write, and manage) Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage code repositories, create and manage pull requests and code reviews, and to receive notifications about version control events via service hooks.
vso.dashboards_manage Team dashboards (manage) Grants the ability to manage team dashboard information
vso.dashboards Team dashboards (read) Grants the ability to read team dashboard information
vso.entitlements Entitlements (Read) Provides read only access to VSTS licensing entitlements endpoint to get account entitlements.
vso.extension Extensions (read) Grants the ability to read installed extensions. vso.extension_manage
vso.extension_manage Extensions (read and manage) Grants the ability to install, uninstall, and perform other administrative actions on installed extensions.
vso.extension.data Extension data (read) Grants the ability to read data (settings and documents) stored by installed extensions. vso.extension.data_write
vso.extension.data_write Extension data (read and write) Grants the ability to read and write data (settings and documents) stored by installed extensions.
vso.gallery Marketplace Grants read access to public and private items and publishers. vso.gallery_publish
vso.gallery_manage
vso.gallery_acquire
vso.gallery_acquire Marketplace (acquire) Grants read access and the ability to acquire items.
vso.gallery_publish Marketplace (publish) Grants read access and the ability to upload, update, and share items. vso.gallery_manage
vso.gallery_manage Marketplace (manage) Grants read access, the ability to publish and manage items and publishers.
vso.identity Identity (read) Grants the ability to read identities and groups.
vso.notification Notifications (read) Provides read access to subscriptions and event metadata, including filterable field values. vso.notification_write
vso.notification_manage
vso.notification_write Notifications (write) Provides read/write access to subscriptions and read access to event metadata, including filterable field values. vso.notification_manage
vso.notification_manage Notifications (manage) Provides read, write, and management access to subscriptions and read access to event metadata, including filterable field values.
vso.packaging Packaging (read) Grants the ability to read feeds and packages. vso.packaging_write
vso.packaging_manage
vso.packaging_write Packaging (read and write) Grants the ability to create and read feeds and packages. vso.packaging_manage
vso.packaging_manage Packaging (read, write, and manage) Grants the ability to create, read, update, and delete feeds and packages.
vso.profile User profile (read) Grants the ability to read your profile, accounts, collections, projects, teams, and other top-level organizational artifacts. vso.extension
vso.extension_manage
vso.extension.data
vso.extension.data_write
vso.gallery
vso.gallery_acquire
vso.gallery_publish
vso.gallery_manage
vso.notification
vso.notification_write
vso.notification_manage
vso.packaging
vso.packaging_write
vso.packaging_manage
vso.profile_write
vso.release
vso.release_execute
vso.release_manage
vso.test
vso.test_write
vso.profile_write User profile (write) Grants the ability to write to your profile.
vso.project Project and team (read) Grants the ability to read projects and teams. vso.project_write
vso.project_manage
vso.project_write Project and team (read and write) Grants the ability to read and update projects and teams. vso.project_manage
vso.project_manage Project and team (read, write, and manage) Grants the ability to create, read, update, and delete projects and teams.
vso.release Release (read) Grants the ability to read release artifacts, including releases, release definitions and release environment. vso.release_execute
vso.release_manage
vso.release_execute Release (read, write and execute) Grants the ability to read and update release artifacts, including releases, release definitions and release envrionment, and the ability to queue a new release. vso.release_manage
vso.release_manage Release (read, write, execute and manage) Grants the ability to read, update and delete release artifacts, including releases, release definitions and release envrionment, and the ability to queue and approve a new release.
vso.test Test management (read) Grants the ability to read test plans, cases, results and other test management related artifacts. vso.test_write
vso.test_write Test management (read and write) Grants the ability to read, create, and update test plans, cases, results and other test management related artifacts.
vso.work Work items (read) Grants the ability to read work items, queries, boards, area and iterations paths, and other work item tracking related metadata. Also grants the ability to execute queries and to receive notifications about work item events via service hooks. vso.work_write
vso.work_write Work items (read and write) Grants the ability to read, create, and update work items and queries, update board metadata, read area and iterations paths other work item tracking related metadata, execute queries, and to receive notifications about work item events via service hooks.

When you register your app, you'll use scopes to indicate which permissions in Visual Studio Team Services your app will require. When your users authorize your app to access their account, they'll authorize it for those scopes. When you call to request that authorization, you'll pass the same scopes that you registered.

Q&A

Q: Can I use OAuth with my phone app?

A: No. Right now, Visual Studio Team Services only support the web server flow, so there's no supported way to implement OAuth for Visual Studio Team Services from an app like a phone app, since there's no way to securely store the app secret.

Q: What errors or special conditions do I need to handle in my code?

A: Make sure that you handle these conditions:

  1. If your user denies your app access, no authorization code is returned. Don't use the authorization code without checking for that.
  2. If your user revokes your app's authorization, the access token is no longer valid. When your app uses the token to access data, a 401 error is returned. You'll have to request authorization again.

Q: I want to debug my web app locally. Can I use localhost for the callback URL when I register my app?

A: Visual Studio Team Services does not allow localhost to be the hostname in your callback URL. You can edit the hosts file on your local computer to map a hostname to 127.0.0.1. Then use this hostname when you register your app. Or, you can deploy your app when testing to a Microsoft Azure website to be able to debug and use HTTPS for the callback URL.

Q: Is there a C# sample that implements OAuth to call Visual Studio Team Services REST APIs?

A: Yes, in GitHub.

Q: I get an HTTP 400 error when I try to get an access token. What might be wrong?

A: Check that you set the content type to application/x-www-form-urlencoded in your request header.

Q: Can I use OAuth with the SOAP endpoints as well as the REST APIs?

A: No. OAuth is only supported in the REST APIs at this point.