Creating API tokens

To use asymmetric encryption, you need to generate an ECDSA-SHA256 public and private key pair using the OpenSSL command-line tool. The public and private key pair are generated using the prime256v1 curve. For more information on ECDSA, see RFC 6605.

To create a public / private key pair:

1. Run the following command to generate an elliptical curve (EC256) private key:

   Copy

   openssl ecparam -genkey -name prime256v1 -out ec256-key-pair.pem

2. Run the following command to convert the EC256 private key into PKCS#8 PEM format:

   Copy

   openssl pkcs8 -topk8 -inform pem -in ec256-key-pair.pem -outform pem -nocrypt -out privateKey.pem

3. Run the following command to generate the EC256 public key:

   Copy

   openssl ec -in ec256-key-pair.pem -pubout -out publicKey.pem

The following files are created in the OpenSSL /bin folder:

• ec256-key-pair.pem: the elliptical curve parameters and private key.

  It’s imperative that you keep your EC private key secure. It's comparable to a password—don’t share it with anyone.

  Example
  Copy 1 2 3 4 5 6 7 8 -----BEGIN EC PARAMETERS----- BggqhOPExample== -----END EC PARAMETERS----- -----BEGIN EC PRIVATE KEY----- MHcCAQEEIM+oHeLG0rhP8lPYW4IWky0de8ayDgM+mCWfWmH/zCZEoAoGCCqGSM49 AwEHoUQDQgAEs1gtNZG++HYIi7hLiXpM74OIbkF+lTYPowrgRzVXT+uENXVGbBcb wc0nsh0r86jK+84j+tECKeyPairExample== -----END EC PRIVATE KEY-----

• privateKey.pem: the EC256 private key in PKCS#8 PEM format

  It’s imperative that you keep your private key secure. It's comparable to a password—don’t share it with anyone.

  Example
  Copy 1 2 3 4 5 -----BEGIN PRIVATE KEY----- ABcDEFGHICPJqF12Zd7Y2xUabq34odtrqTI3W7EWJwRTvF7ewETXoAoGCCqGSM 49AwEHoUQDQgAER5wRCKw7wCTjaQ7/FTmMRFhl3+Rg4a29qkrL0QsxOIc6Ae/n WYU3CifATMvHBxcCQ+B8U6PrivateKeyExample== -----END PRIVATE KEY-----

• publicKey.pem: the EC256 public key that you upload to the Secure Endpoint Console

  Example
  Copy 1 2 3 4 -----BEGIN PUBLIC KEY----- ABcdEfGHIoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9 q9UU8I5mEovUf86QZ7kOBIjJwqnzD1omagedT9POxgPublicKeyExample== -----END PUBLIC KEY-----

To access an Absolute API, you need to create an API token.

To create an API token:

1. Log in to the Secure Endpoint Console as user with the Manage permission for API credentials.
2. On the navigation bar, click Settings > API management.
3. Click Create API token.
4. In Add title, give the token a name.
5. [Optional] To help identify the token, click the field under the title and enter a Description for this request.

6. Do one of the following:

   Asymmetric encryption

   1. Select Upload public key.

   2. Enter the public key you generated in Creating Elliptical Curve keys. The starting -----BEGIN PUBLIC KEY----- and ending -----END PUBLIC KEY----- lines are optional.

      The following is an example of a public key with the starting and ending tags:

      Copy

      1
      2
      3
      4
      -----BEGIN PUBLIC KEY-----
      ABcdEfGHIoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9
      q9UU8I5mEovUf86QZ7kOBIjJwqnzD1omagedT9POxgPublicKeyExample==
      -----END PUBLIC KEY-----

   Symmetric encryption

   • Select Generate Token.

7. Click the Expiration date field and set an expiration date at least one day in the future by doing one of the following:

   • enter a date in YYYY-MM-DD format
   • use the Calendar picker to select a date
   • select one of the predefined expiry date ranges

   If you don't set the Expiration, the expiration date defaults to 90 days.

8. To change the token's permissions, select View, Manage, and Other Actions for each permission you want to add. Clear View, Manage, and Other Actions for each permission you want to remove. If you select Manage for a permission, View is automatically selected. If you don't change the permissions, the token has the same permissions as your assigned user role.

   Token permissions can't be modified once the token is created.

   To include all the permissions assigned to your user role, scroll to the bottom of the Permissions section and click Select All. To remove all permissions, click Clear.

   Assigned device group is based on your user account and is not editable. If your assigned device groups change in the future, this API token is not updated.

9. [Optional] Enter the IP addresses that you want to allow to access the APIs. Both IPv4 and IPv6 IP addresses in single and CIDR format are accepted. If no IP addresses are entered, the APIs can be accessed from any IP address. Approved IP addresses can be added to a token after it has been created.

   1. Enter or copy and paste one of the following in to Approved IP Address:

      • an individual IP address
      • a list of IP addresses separated by a space ( ), comma (,), semi-colon (;), or line break

   2. Click Add or press Enter.

      IP addresses are listed below the entry field. Validation is done on each IP address. If validation fails, you see Invalid IP address. Do one of the following:

      • To delete the IP address, click .
      • To edit the IP address, click in the IP address, make your changes, and press Tab or click away from the IP address. Validation is done on the updated IP address.

   Duplicate entries are ignored.

10. Click Save.

    After you click Save, none of the fields can be edited. To make changes, you need to edit the token.

11. From the Token Key Details section, do one of the following to capture the token information:

    • To copy the token information

      1. Click in the Token ID field or click Copy beside the token ID and paste the token ID to a text file.
      2. [Generated token only] Click in the Secret key field or click Copy beside the secret key and paste the secret key to the text file.
      3. Save the file to a secure location on your computer.
    • [Generated token only] To download the token ID and secret key, click Download Token. The token ID and secret key are downloaded in a .token file to your operating system's downloads folder. You can use a text editor, such as Notepad, to open the file.

    If you close this dialog without downloading or copying the secret key for generated tokens, you can't retrieve the information later. Record or save the secret key now, or you must delete this token and create a new one.

12. After you have captured the token information, click (Close).

On the API management page, the new token is added to your list of tokens. An API token updated event is logged to Event History. The user that created the token and all users assigned to the default System Administrator role receive an email indicating that a new API token has been created.

It’s imperative that you keep your private keys and secret keys secure. They're comparable to passwords—don’t share them with anyone.

Newly created tokens must have an expiry date. By default, the expiry date is 90 days from the day the token is created. You can set the expiry date to be up to one year from the creation date. You can continue to use the token until 23:59:59 UTC on the day the token expires.

The user associated with the token and all users assigned to the default System Administrator role receive an email three days before the expiry date. Before a token expires, the expiry date of the token can be extended up to one year from the day that you are editing the token.

The user associated with the token and all users assigned to the default System Administrator role receive a second email when the token expires. An API Token expired event is logged to Event History. You can view expired tokens in the Secure Endpoint Console. Expired tokens are labeled Expired in API management and can't be modified.