Authentication with Ascribe APIs

The various Ascribe™ APIs, such as the Ascribe Coder API, share a common authentication operation.  You authenticate with the API by a POST to the /Sessions resource.  To interact with any of the other resources in the APIs you must include a token returned in the POST response in an HTTP header.

Obtaining an Authentication Token

To obtain an authentication token, POST to the /Sessions resource.  The body of the POST request contains the login credentials for an Ascribe user: Account, Username, and Password.  The body of the POST request has this form:

{
  "account": "MyAscribeAccount",
  "userName": "apiuser",
  "password": "--------"
}

Here we are authenticating as with the user name apiuser, on the MyAscribeAccount.  We recommend that you create an Associate in Ascribe exclusively for the API.  This is because the time accounting features of Ascribe will attribute activity initiated via the API to this user.  This makes interpretation of the time accounting reports easier.

The POST response has this form:

{
  "authenticationToken": "0e2338c4-adb4-474a-a26a-b9dbe1b32ac8",
  "bearerToken": "bearer eyJhbGciOiJSUzI1NiIsInR5cC ... WiiVzXPhdgSWNvH1hNOIirNmg"
}

The value of the bearerToken property is actually much longer than shown here.  You can use either of these tokens (but not both) in subsequent operations with the API.

Differences between the Token Types

The authenticationToken returned by the /Sessions resource expires after 30 minutes of inactivity with the API.  In other words, you must perform an operation with the API at least once every 30 minutes.  After that you must obtain another token from the /Sessions resource.  The token will remain valid indefinitely if you do make a request at least once every 30 minutes.

The bearerToken does not expire.  Once you have obtained a bearerToken it will remain valid until the login credentials of the user are changed.

Using Authentication Tokens

To use the authenticationToken returned by the /Sessions resource, include it in an HTTP header.  The key of the header is authentication, and the value is the authenticationToken.  The raw HTTP request looks like this:

GET /coder/studies
accept: application/json, text/json, application/xml, text/xml
authentication: 207e5be1-c3fa-4ff6-bbc7-475a367ec095
cache-control: no-cache
host: webservices.languagelogic.net
accept-encoding: gzip, deflate

To use the bearerToken, use an HTTP header whose key is “authorization” and value the bearerToken.  The raw HTTP request looks like this:

GET /coder/Studies
accept: application/json, text/json, application/xml, text/xml
authorization: Bearer eyJhbGciOiJSUzI1NiI ... lJqc7nPxcFdU3s90BkOPlPF6wTxkzA
cache-control: no-cache
host: webservices.languagelogic.net
accept-encoding: gzip, deflate

Summary

The Ascribe APIs require the remote client to authenticate.  The remote client authenticates by providing user credentials, and uses one of the two tokens returned in subsequent operations with the API.

See the Ascribe Coder API documentation, and the Ascribe CX Inspector API documentation for more information.