Using the Web Server Authorization Flow
Go Up to Obtaining Authorization to Use the API
The Web Server Authorization Flow allows client applications that are accessible via HTTP requests, such as web server applications, to obtain an API access token.
This authorization flow consists of the following steps:
- Obtain an authorization code:
- Your client application opens Team Server in a web browser, using an URL with a set of query parameters that indicate the type of access that your client application requires, as well as a callback URL where Team Server can reach your client application.
- Team Server handles the user authentication and consent. If the user agrees, Team Server performs a request against the callback URL that your client application provided as a query parameter in the URL (in the previous step). This request includes a query parameter with an authorization code.
- Exchange the authorization code for an access token:
- Your client application, after it receives the authorization code, performs a request against Team Server providing the authorization code.
- Team Server responds with an access token.
You obtain a refresh token as well as an access token. You can use that refresh token to obtain a new access token when your current access token expires.
Obtaining an Authorization Code
You application must open in a web browser an URL that points to the target Team Server installation. In this URL, you must include query parameters indicating the type of API access that your client application requires. Team Server authenticates the user, informs the user of the access request, and allows the user to choose whether to grant your client application the requested access permissions or not.
The URL that you must open is http://teamserver.example.com/api/oauth/authorize . You must append the following query parameters to this URL:
Item | Example | Description |
---|---|---|
response_type |
code |
The type of response that Team Server must return in the request to your callback URL. Provide the value code here to request that Team Server returns an authorization code in the request to your callback URL. |
client_id |
6a2a39ba-9688-493d-b348-187468f599ae |
The ID of your client application, as registered in the target Team Server installation. |
redirect_uri |
http://myapp.example.com/oauthcallback |
The callback URL of your client application. The value of this parameter must exactly match one of the values used when registering the app. |
scope |
read+write |
Space-delimited list of access scopes. Possible values are:
The default value is read+write . |
state |
Custom string |
Custom string that you want your client application to receive in the request to your callback URL. You can use this parameter for anything you want. For example, you can use it to redirect users to the correct resource in your site. |
The following is an example URL:
- http://teamserver.example.com/api/oauth/authorize?response_type=code&client_id=6a2a39ba-9688-493d-b348-187468f599ae&redirect_uri=http://myapp.example.com/oauthcallback
After your user logs into Team Server and grants your client application access to the API, Team Server performs a request against your callback URL providing a code query parameter. For example:
- http://myapp.example.com/oauthcallback?code=6U4MUI
Store that code.
Exchanging an Authorization Code for an Access Token
Once you have an authorization code, you must perform a request against http://teamserver.example.com/api/oauth/token . You must append the following query parameters to this URL:
Item | Example | Description |
---|---|---|
code |
6fGVc2 |
The authorization code that your client application previously obtains. |
client_id |
6a2a39ba-9688-493d-b348-187468f599ae |
The ID of your client application, as registered in the target Team Server installation. |
client_secret |
a28e0ca4-27cb-4361-bf97-3b26c612d66a |
The secret of your client application, as registered in the target Team Server installation. |
grant_type |
authorization_code |
The type of your access token request. Provide the value authorization_code here, as your request to Team Server is for an access token in exchange for your authorization code. |
redirect_uri |
http://myapp.example.com/oauthcallback |
The callback URL of your client application. |
The following is an example URL:
- http://teamserver.example.com/api/oauth/token?code=6fGVc2&client_id=6a2a39ba-9688-493d-b348-187468f599ae&client_secret=a28e0ca4-27cb-4361-bf97-3b26c612d66a&grant_type=authorization_code&redirect_uri=http://myapp.example.com/oauthcallback
Team Server responds in JSON format. The server response includes the following information:
{
// Token to include in every API request to get access.
"access_token": "d4ac0c07-0013-4939-b9ee-0112fdbb7d64",
// Type of token. This is always "bearer".
"token_type": "bearer",
// Token that you can use to get a brand-new access token without further user interaction.
"refresh_token": "bcd5a78c-9f0a-4ba6-9baa-5872e5acf7bb",
// Number of seconds before the access token expires. Default value is 86400 (1 day).
"expires_in": 86399,
// Granted scope.
"scope": "read write"
}
You can now start using the Team Server API, including the provided access token in every API request.