Auth Tokens

Auth tokens, or API keys, consist of a (usually secret) string that authenticates REST calls and associated properties. An auth token is a typically long string with two nodes, such as demo_full:1. Live API Creator maps the second node to your roles for authorization. You can assign an auth token to one or more roles.

For more information about authorization, see Authorization.

Auth tokens are required for almost all REST calls, with a few exceptions, such as @authentication (since its purpose is to acquire an auth token), @heartbeat, and @license. Calls that do not include an auth token are returned with HTTP status code 401.

You can specify auth tokens in a REST call:
  • For GET calls, as a URL parameter, for example:
    .../customers?auth=ABCDEF123456:1
    Note: Specifying auth tokens in a REST call as a URL parameter is not secure but it can be convenient for debugging.
  • For all calls including GET, as an HTTP header, for example:
    Authorization: CALiveAPICreator ABCDEF123456:1
The authentication service automatically creates auth tokens. You can also create them using the API Creator, the API, or the command line.

Attributes

 Name Type Required Description
 ident integer YThe unique identifier for this object
 ts timestamp YThe date and time when this object was created or last modified
 name string(100) YThe name for the auth token.
 description string(2000) N 
 apikey string(128) YThe actual auth token. On insertion, leave it blank if you want the system to generate the auth token, or provide a value if you want a "fixed" auth token.
 status char Y"A" for Active or "D" for deactivated.
Note: Using deactivated auth tokens results in authentication errors.
 expiration timestamp NIf specified, the date and time at which this auth token will become invalid.
 logging string(200) NA comma-separated list of logging levels for the various loggers. For example:
admini=FINE,buslog=FINE,depend=FINE,generl=FINE,persis=FINE,engine=FINE,
resrcs=FINE,securi=FINE,sysdbg=FINE,ulogic=FINE

If all loggers should be at the same level, you can also use:
*=FINE

 user_identifier string(100) NIf specified, the identifier for the user (typically some sort of user name or user ID). This should ideally allow identification of the user, but that is not required.
 data string(1000) NIf specified, a comma-separated list of name/value pairs that will be available in the security context for this auth token, for example:
employeeNo=12345,region=ASIA
 origin char NIndicates who created this auth token. 'A' means that it was created by the authentication service.
 project_ident integer YThe ident of the project/API that contains this auth token