Auth Tokens

An auth token (the apikey endpoint) consists 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 abcdefg:1. The first part (abcdefgis the apikey. The second part (:1) is unused. Live API Creator maps the second node to your roles for authorization. You can assign an auth token to one or more roles.

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

For more information:

  • About authorization, see Authorization.
  • About how to generate user authentication, including information about obtaining an auth token automatically during sign-on using the @authentication resource endpoint, see Authentication.

Attributes

The following table includes the apikey endpoint 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.
Important! 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

More Information

For more information about the user authentication-generation process, including how to obtain an auth token and how to specify the auth token on API calls, see Authentication.