Using token-based authentication

To determine whether the server accepts or requires tokens, you can use the RequiresTokens method of the Service Catalog. If RequiresTokens is true, you can obtain the URL of the token service with the GetTokenServiceURL() method.

Catalog myCatalog = new Catalog();

myCatalog.Url = "http://localhost:6080/arcgis/services";

if (myCatalog.RequiresTokens())


      string tokenServiceUrl = myCatalog.GetTokenServiceURL();


Of course, you may already know the URL of the token service from the server's administrator. The token service is at a URL such as http://localhost:6080/arcgis/tokens. Once you know the token service URL, you can request a token, assuming you have a valid user name and password for the ArcGIS Server instance. You can use the WebRequest class to make a request for the token. Note that the request may encounter problems such as an unresponsive server, incorrect password, etc. You should wrap the request in a try-catch block to deal with errors.

string url = tokenServiceUrl + "?request=getToken&username=myuser&password=secret";

System.Net.WebRequest request = System.Net.WebRequest.Create(url);

System.Net.WebResponse response = request.GetResponse();

System.IO.Stream responseStream = response.GetResponseStream();

System.IO.StreamReader readStream = new System.IO.StreamReader(responseStream);

string myToken = readStream.ReadToEnd();

The token will be a long string of characters. It must be appended to the URL of the web service endpoint with each request. You do not need to include it within the request itself. The example above for the map server would be modified to include the token:

MapService_MapServer mapservice = new MapService_MapServer();

mapservice.Url = "http://localhost:6080/arcgis/services/MapService/MapServer?token=" + myToken;

Tokens expire within a time period designated by the server administrator. The expiration timeout window may vary from a few minutes to several days. Currently there is no programmatic method to ascertain the token timeout. Therefore you must account for token expiration in your code, and obtain a new token when required.

Currently the way to detect timeout of a token is to catch the exception thrown and to check the response code. A code of 498 indicates an expired or otherwise invalid token. A code of 499 indicates that a token is required (if no token was submitted). Once you determine that a new token is needed, you can request one, update the server's URL with the token, and repeat the request.

MapImage mapimg = null;

try {

      mapimg = mapservice.ExportMapImage(mapdesc, imgdesc);


catch (System.Net.WebException webExc) {

      System.Net.HttpWebResponse webResp = webExc.Response as System.Net.HttpWebResponse;

      if (webResp != null) {

            int statusCode = (int)webResp.StatusCode;

            if (statusCode == 498 || statusCode == 499) {

                  // call a method (not shown here) that obtains a new token

                  string newToken = getToken();


                  mapservice.Url = "http://MyWebServer/arcgis/services/MapService/MapServer?token=" + newToken;

                  mapimg = mapservice.ExportMapImage(mapdesc, imgdesc);