API: Overview of API keys and FAQ

Edit online

Application Programming Interface (API) keys are a way to authenticate with Apptio service APIs without passing in user credentials. An API key contains a key pair that includes a public key and a secret key. This combination of public and secret keys is used as credentials to authenticate requests. Each API key can have a maximum of two key pairs. When a new API key is created, it creates a key pair. You can add or delete key pairs up to a maximum of two key pairs. API keys provide the following benefits:

  • Security: API keys are randomly generated and have longer character strings. Apptio’s API keys are 60 characters long. The higher entropy makes it difficult for attackers to compromise.
  • Independence: In programmatic calls, using an API key keeps the master account (that is, the parent User account) credentials from being exposed to other users in the system (such as co-workers).
  • Limited exposure: The secret key is exposed to the user only during the creation of an API key. The user is instructed to securely store the secret key. If the secret key is lost or compromised, a new key can be created.
  • Key rotation: The ability to have two active key pairs allows users to rotate the key pairs without breaking any automation or programmatic access. You can configure the API Key Rotation Policy in Domain Properties.
  • Traceability: API keys are always linked to a parent user account and provide the same level of traceability that a normal interactive session provides.

Who Can Create API Keys?

The API Keys settings in Domain Properties control whether or not API Keys are supported in the Domain, and if so, who can create them. If API Keys are enabled, Admins can create API Keys for themselves and others. If Restrict API Key Creation is false, any User can create API keys for their own User.

Create and manage API keys

To create or manage API keys for your own User, click on the Profile button at the top of the page, choose User Profile and click on the API keys tab. To create or manage API keys for another User, click Home in the left navigation panel, select the Domain of the User, then find the user in the table. Click on Details, then click on the API keys tab.

Create an API key
  1. On the API Key tab, click Create API Key.
  2. Type a Key Name and Description.
  3. Select an expiration policy, and select Add.
  4. Note the public key. Select Show to display the secret key. You can only view the secret key while creating the API key. You will need this key during programmatic authentication. Save the secret key in a safe location.
  5. Select one of the following options:
    • Done Return to the Users page and grant API key access to environments at a later time.
    • Grant Access: Select from the list of environments for which the user already has access, then click Next. Select one or more Roles for the API key. Select Next, and then select Grant Access.
Manage API keys
  1. On the API Keys tab, select from one of the following options:
    • Show Key Pairs: Display or hide the public keys and expiration dates (this option is only in the Profile view).
    • Grant Access: Select from the list of environments for which the user already has access, then click Next. Select one or more Roles for the API key. Select Next, and then select Grant Access.
    • Disable: Disable a key.
  2. Click on an API Key to show the Details Pane for the API Key:
    • Properties - Shows the Name, Rotation Policy and Description of the API Key. Click Edit to change any of these values.
    • Key Pairs - Shows the Key Pairs associated with the API Key with their Expiration Dates. To Add a Key Pair, click the +. To Delete a Key Pair, check the box at the start of the Row, then click Delete.
    • Access - Shows Environment access associated with API Key with options to Change and Revoke access.
Use API keys

To use the API keys in your scripts and programs, refer to the following topics:

API key FAQ

What is the expiration policy for an API key?

This is configurable in Domain Properties.

Who can create and manage API keys?

This is configurable in Domain Properties.

What Environments and Roles are available to API keys?

API keys can be granted access to same the Environments and Roles that the parent User has for any Environment in the User's Domain. For security reasons, API keys cannot be granted access to Environments that are not in the parent User's domain.

Can I rotate my API keys?

You can create multiple API keys for a single user (parent user) account and each API key can have two key-pairs. All the keys are active and valid, unless they have already expired or have been explicitly disabled or deleted. These features allow you to update scripts and perform other periodic tasks with a new key-pair for the same API key without interruptions. After updating the scripts, you can delete the unused and expired key-pairs.

Note:

If a parent User is disabled, all the associated API Keys are also disabled.

Can API token generation be disabled on a per user basis?

Yes.

Is there an audit log of API access?

Yes, API Keys are included in all Audit Reports.

What parameters are used for session encryption?

https TLS 1.2 AES256