Obtain and Use Authentication Tokens

Your API can use authentication tokens directly instead of authenticating API users using the built-in authentication authentication provider. API user authentication results in an authentication token. API Server passes this authentication token on all subsequent requests and indicates a set of roles that define what the authentication token is authorized to do.
lac42
Your API can use authentication tokens directly instead of authenticating API users using the 
built-in authentication
 authentication provider. API user authentication results in an authentication token. API Server passes this authentication token on all subsequent requests and indicates a set of roles that define what the authentication token is authorized to do.
In this article:
Obtain an Authentication Token
Your APIs can obtain an authentication token using one of the following methods:
For more information about authentication tokens, including a list of authentication token attributes, see The apikeys Endpoint.
Obtain an Authentication Token Dynamically During Sign-On
If you have specified the 
built-in authentication
 authentication provider or a custom JavaScript authentication provider as the authentication provider for your API, you can authenticate an API user and obtain an authentication token dynamically during sign-on using the 
@authentication
 resource endpoint.
The following is an example. The following URL obtains the authentication token using the 
@authentication
 RESTful endpoint for the 
built-in authentication
 authentication provider:
http://<base_api_creator_url>/rest/default/demo/v1/
@authentication
For more information about this RESTful endpoint, see System REST Endpoints.
Create authentication tokens and test the
@authentication
RESTful endpoint in the REST Lab.
Obtain an Authentication Token using API Creator
With proper authorization, you can obtain an authentication token using API Creator. These authentication tokens are not associated with API users and are typically used for machine-to-machine situations. You create them in your API using API Creator.
Best Practice:
Access resources for the selected roles using these authentication token.
 If you do not intend to widely publicize your authentication token (it is for a private API), share your authentication token only with trusted sources.
Follow these steps:
  1. With your API open, in the Manage section, click 
    Auth Tokens
    .
    The Key page appears by default.
  2. Click 
    Add
    .
  3. Modify the following fields, and then save your changes:
    Auth Token name
    Defines the name for the authentication token. This name is the name of the authentication token that API Creator presents in lists, for example, in the Rest Lab.
    Auth Token value
    Defines the value that 
    CA Live API Creator
     passes to the REST calls to authenticate the call. You can accept the randomly-generated 20-character value or specify a value.
    User identifier
    Defines the login identifier for the API user for this authentication token. You can associate an API user to this authentication token by entering a value in this field. If you have specified the built-in authentication authentication provider as the authentication provider for your API, this field is auto-populated when 
    CA Live API Creator
     creates the authentication token. Use this field for auditing and traceability. 
    CA Live API Creator
     does not use this field.
    Required: 
    No
    Expiration
    Defines the point in time after which this authentication token is no longer valid. This field is a 
    TIMESTAMP
     datatype.
    Required: 
    No
    Globals
    Defines a comma-separated list of name/value pairs that are available at runtime for this authentication token, where each name and value are legal JavaScript strings. Enter "name"="value", "anotherName"= "anotherValue" for descriptive comments for this authentication token. You can access these values at runtime.
    Required: 
    No
    Description
    Required: 
    No
The authentication token is created.
Use HTTP Basic Authentication to Return an Authentication Token
When you use HTTP basic authentication to return an authentication token, API Server passes the username and password for the API user it receives to the authentication provider. The HTTP basic authentication username cannot contain a colon (:).
When validated, 
CA Live API Creator
 generates the authentication token. 
CA Live API Creator
 avoids calling the authentication provider for each request by caching this generated authentication token.
Your authentication provider might force the authentication provider to be called more frequently by setting the expiry time for the token to be short.
CA Live API Creator
 uses the 
Realm (Protection Space)
 value for the realm in the WWW-Authenticate Challenge response. If you do not specify a 
Realm (Protection Space)
 value, 
CA Live API Creator
 omits the realm from the WWW-Authenticate Challenge response. 
CA Live API Creator
 encodes the value with UTF-8 before it sends it. It replaces invalid characters within the realm-quoted string with an ASCII space (x20) characters.
HTTP Authentication References
The following is a list of HTTP authentication references:
Enable your API for Basic Authentication
  1. In API Creator, create an API.
    For more information, see Creating APIs.
  2. Configure your API. Complete the following steps:
    1. Specify the 
      built-in authentication
       authentication provider as the authentication provider for your API. On the 
      Details
       tab, select the 
      built-in authentication
       authentication provider from the 
      Authentication provider
       field, and then save your changes.
      For more information about how to control the API details, see API Properties.
      The API is using the built-in authentication provider.
      : This authentication provider is selected by default.
    2. Enable your API for basic authentication. Click the 
      Settings
       tab, select the 
      Enable HTTP Basic Authentication
       checkbox, and then save your changes.
      : This checkbox is selected by default.
      For more information about how to define this API setting, see API Properties.
      You have enabled your API for basic authentication.
    3. Add the API users. In the Manage section, click 
      Users
      , click 
      Add
      , define the API user and assign a role to the API user, and then save your changes.
      For more information about how to add API users and assign roles to API users if you are using the
      built-in authentication
       authentication provider, see Authenticate API Users using the Built-in Authentication Provider.
Example: Retrieve a Resource
After you have enabled your API for basic authentication, you can perform a GET on a resource. For example, using a browser or using an HTTP client tool such as cURL, issue the following command:
The following URL is for the single-user demonstration package of
CA Live API Creator
that is based on Jetty.
curl --trace - -X GET "http://demo:[email protected]:8080/rest/default/demo/v1/demo:customer"
demo:Password
 is the 
<username>:<password>
 that HTTP basic authentication uses.
Specify the Authentication Token on API Calls
Prerequisite:
 You have obtained the authentication token. You can specify the authentication token using the following methods:
  • (GET requests only) Specify it in the URI.
     This method is not secure. This method is recommended only when it is not convenient to put the authentication token in a header. For example, if you want to try your API from a web browser. Browser caches and web log files contain the authentication token in plaintext.
Specify the Authentication Token in the HTTP Header
Specify the authentication token in the HTTP header using the following syntax:
Authorization: CALiveAPICreator 
<apikey>
:1
The header name is 
Authorization
. The authorization prefix indicates that this header is specifically for API Server.
While header name is 
Authorization
, this header is used for authentication. The name of the header is dictated by the HTTP standard.
Specify the Authentication Token in the URI
Prerequisite: 
You have authorized API users to specify their authentication token on the URL.
For more information about authorizing API users to specify authorization parameters in URLs, see API Properties.
You can specify an authentication token in a REST call as a URL parameter only for GET requests. Use the following syntax:
curl -G https://server.acme.com/rest/acme/myproject/v1/customer?auth=
<apikey>
:1
View your Generated Authentication Tokens
With your API open, in the Manage section, click 
Auth Tokens
. The last ten authentication tokens (per server) are listed in the 
Auth Tokens
 list. You can limit the list to only the authentication token name using named filters.
For more information about named filters, see Structured Filters.
Advanced Usage
You can change passwords and validate an existing authentication token using the 
@authentication
 RESTful endpoint.
Disable an Authentication Token
You can disable the authentication token by including the 
apikey
 attribute and setting the 
disable
 attribute to 
true
 in the payload:
Use the following syntax in the payload:
{ "apikey": "1234567890abcdef12345", "disable": true }
Response
If the authentication token is still valid and active, the following response is expected:
 { "apikey": "1234567890abcdef12345", "disabled": true }
API Server disables the authentication token. This response is idempotent and is considered a success even if the key has already expired or has been marked as disabled. API Server returns an error if the authentication token is not found.
Revalidate the Authentication Token
You can revalidate the authentication token and check the expiration date by including the 
apikey
 attribute in the payload.
Use the following syntax in the payload of a POST request:
{ "apikey": "1234567890abcdef12345" }
Response
The following response is expected:
{ "apikey": "1234567890abcdef12345", "expiration": "2014-12-31T23:59:59.999"} 
API Server returns the existing expiration date for the authentication token. If the authentication token has expired, API Server returns an expired error. If the authentication token is valid, API Server returns a normal response as though the API user had logged in successfully to API Creator using their username and password. API Server returns the existing authentication token (with its original expiry).
Post Password Change Authentication Requests with Custom Authentication Providers
When you POST a password change authentication request, on successful log in, API Server calls the 
authenticate()
 method with 
true
 value for the 
enablePasswordChange!
 argument. Your custom authentication provider can implement or ignore the request.