API keys referred to as auth tokens
. They consist mostly of a (usually secret) string that authenticates REST calls, along with some associated properties.
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.
Auth tokens can be specified in a REST call:
- for GET calls, as a URL parameter, e.g.
.../customers?auth=ABCDEF123456:1 Note that this is not recommended as it is not secure, but it can be convenient for debugging.
- for all calls including GET, as an HTTP header, e.g.
Authorization: CALiveAPICreator ABCDEF123456:1
Auth tokens are created automatically by the authentication service, but they can also be created "by hand", either in the API Creator, or using the API or command line.
| Name|| Type|| Required|| Description|
| ident|| integer|| Y|| The unique identifier for this object|
| ts|| timestamp|| Y|| The date and time when this object was created or last modified|
| name|| string(100)|| Y|| The name for the auth token.|
| description|| string(2000)|| N|| |
| apikey|| string(128)|| Y|| The actual auth token. On insertion, this will be generated by the system if left blank, or a value can be provided if you want a "fixed" auth token.|
| status|| char|| Y|| Can be "A" for Active or "D" for Deactivated. A deactivated auth token cannot be used -- it will result in an authentication error.|
| expiration|| timestamp|| N|| If specified, the date and time at which this auth token will become invalid.|
| logging|| string(200)|| N|| A comma-separated list of logging levels for the various loggers, e.g.:|
If all loggers should be at the same level, you can also use:
| user_identifier|| string(100)|| N|| If 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)|| N|| If specified, a comma-separated list of name/value pairs that will be available in the security context for this auth token, e.g.:|
| origin|| char|| N|| Indicates who created this auth token. 'A' means that it was created by the authentication service.|
| project_ident|| integer|| Y|| The ident of the project/API that contains this auth token|