Skip to main content
Cartegraph Campus

Authentication for REST API

This feature may not be available in every package. Not sure if you have this feature or you want to learn more about it? Send us a message at support@cartegraph.com. 

Cartegraph's API is a licensed product that requires a purchase and verified ownership before production use.

Authenticate

  • Purpose: Allows a client to authenticate with REST API.
  • HTTP Method: POST
  • URL: https://yourserver.com/cartegraph/api/v1/authenticate
  • Required Parameters: 
    • userName OMS User Accounts User Name assigned to the client, which is different than the Esri User Name
    • password  - Password for the OMS User Accounts
    • isInternalRequest - (Optional) Boolean should be true to check for Internal Request role security.

Example Request

Authenticate:

POST https://yourserver.com/cartegraph/api/v1/authenticate

{
    "username": "MyUser",
    "password": "MyPassword",
    "isInternalRequest": false
}

Responses

Success

A success object is returned on a successful sign in that contains the amount of time the session is active (in seconds) and a 200 OK status code. The caller should automatically store the cookie.

{ "LogOnStatus": 0, "Expires": 3600 }

Error

Providing invalid credentials will result in a 401 Unauthorized status code in the response. An ApiError object is returned.

{ "Message": "The user name or password is incorrect." }

Attempting to pass user name or password in the authentication URL will result in a 400 Bad Request status code in the response. An ApiError object is returned.

{ "Message": "Cannot pass user name or password through the URL." }

Attempting to access the API prior to being authenticated or after a valid authentication has expired will result in a 401 Unauthorized status code in the response. An ApiError object is returned.

{ "Message": "Authentication Required for API Access." }

Attempting to access the API with an inactive user account will result in the following response:

{ "Message": "The user account is inactive." }

Attempting to access the API when the system is down for maintenance will result in a 503 Service Unavailable status code in the response. An ApiError object is returned. (New for v18 - Fall 2018)

{"Message": "Service currently unavailable."}


Sign Out

(New for v22.3)

  • Purpose: Allows a client to sign out of their current session (invalidate their authentication cookie) with REST API.
  • HTTP Method: POST
  • URL: https://yourserver.com/cartegraph/api/v1/authenticate/signout

Example Request

POST https://yourserver.com/cartegraph/api/v1/authenticate/signout

Response

Calling this method will return a 200 OK status code and an empty object in the response. A new authentication cookie will be sent back in the header that is now expired. The caller should automatically store the new (expired) cookie. Thus, all subsequent calls to the API will result in a `401 Unauthorized` status code in the response until you perform another POST Authenticate call.

{}


Session Info

  • Purpose: Allows a client to check information about the current session. Depending on the connecting client, subsequent calls to authenticated OMS methods may update the session expiration automatically. This method may be called periodically to verify how long the session will remain active as well as retrieve an updated authentication cookie.
  • HTTP Method: GET
  • URL: https://yourserver.com/cartegraph/api/v1/authenticate

Example Request

GET https://yourserver.com/cartegraph/api/v1/authenticate

Responses

An object is returned that contains the amount of time the session is active (in seconds), the value of the authentication cookie, information related to System Maintentance and a 200 OK status code.

{
    "Expires": 3600,
    "Cookie": "YOUR_CARTEGRAPH_COOKIE_HERE",
    "CurrentAuthTokenExpiration": 3600,
    "MaintenanceLevel": 0,
    "MaintenanceMessage": "",
    "MaintenanceUser": "",
    "MaintenanceUserFullName: "",
    "RestrictUsersDuringMaintenance": true
}


Cookie Handling

This section is only for cases when a developer needs to manually handle Cookies (uncommon practice).

The API uses ASP.NET Forms Authentication and uses standard Cookies to pass along the token to make authorized calls.  Without the authorization Cookie most API methods will come back with a 401 Unauthorized.

When you call POST Authenticate, the majority of programming languages and environments automatically handle the authentication Cookie. We recommend using a library that automatically handles Cookies. However, if that's not available the following steps are required.

  1. Call POST Authenticate successfully.
  2. Look for the Response header of "Set-Cookie" and save the value off.
  3. Construct an HTTP header for future OMS API calls like this:

Cookie:.ASPXAUTH_Cartegraph=YOUR_CARTEGRAPH_COOKIE_HERE

If there are continued API calls before the Session-timeout / Expires (after 50% of Session-timeout elapses), the Set-Cookie header will be sent with a fresh Cookie / token on the HTTP Response.

Therefore, it is recommended to watch for the Set-Cookie header on every HTTP Response received and store/use the new Cookie value for subsequent calls. Otherwise, once the Session-timeout has been met from the original response of the POST Authenticate call, you will have to re-issue another POST Authenticate call for a fresh Cookie.

You could accomplish the same result by periodically calling GET Authenticate and update the Cookie with the new Cookie returned in the response body. This would be accomplished by calling GET Authenticate once 50% of the Session-timeout elapses and construct the Cookie HTTP header as shown above from the Cookie that was returned in the GET Authenticate response body called “Cookie”.