Enhanced Access Administration API: Overview of API keys and FAQ

Create and manage Enhanced Access Administration API keys

Enhanced Access Administration API keys are programmed with robust identity control and access management features. For example, you can create a custom role with limited permissions and create an API key that only grants access to this custom role. This limits the API key to only those permissions assigned to the custom role.

1. In the Settings () menu, select Access Administration.
2. On the Access Administration page, select Users.
3. In the Actions column for the user, select Edit.
4. Under API Keys, select Create API Key.
5. Type a Key Name and Description.
6. Select an expiration policy, and select Add. For more information about expiration policy, refer to What is the expiration policy for an API key?
7. 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.
8. Select one of the following options:
   • Skip Grant Access: Return to the Users page and grant API key access to environments at a later time.
   • Grant Access: Select environments for which the user has already been assigned roles, and then select Continue. Select roles for the API key. Select Next, and then select Grant Access.

1. On the Access Administration menu bar, select Users.
2. In the Actions column for the user, select Edit.
3. In the API Keys section, select from one of the following options:
   • Show Key Pairs: Display or hide the public keys and expiration dates.
   • View: Display and manage the API key details (create a new key pair, delete key pairs, delete or disable a key).
   • Grant Access: Select environments for which the user has already been assigned roles, and then select Continue. Select roles for the API key. Select Next, and then select Grant Access.
   • Revoke Access: Revoke or change roles assigned to the API key.
   • Disable: Disable a key.

1. On the Access Administration menu bar, select Users.
2. In the Actions column for the user, select Edit.
3. In the Manage User Environments section, select one of the following options:
   • Change Roles: Change the roles assigned to an API key. For more information, refer to Manage user permissions and roles.
   • Revoke Access: Revoke or change roles assigned to the API key.

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

• Authentication via API keys
• cURL Examples

API key FAQ

What parameters are used for session encryption?

Apptio SaaS solutions, including Cloudability, use API-based connections and data ingestion. Apptio products and solutions do not require direct connections to client’s data centers. Therefore, IPSec is not relevant to Apptio products and services. The API session encryption parameters include the following:

For better security, traceability, and manageability of your programs and scripts, we recommend that you use API keys instead of a service account.

Apptio uses randomly generated 60-character API key. The API keys can be set to expire with one of the following options:

• No Expiration: The API key is valid while the user account is active in the system or until the API key is explicitly removed or disabled.
• 90 Days: The API key automatically expires 90 days from the date of creation unless the user is disabled or the API key is explicitly removed or disabled before the expiration time.

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.

Any Enhanced Access Administration user can create a key pair for their account. Additionally, TBMAs can create and manage API keys for users in their authentication domain.

API keys can be granted access to environments that belong to the parent user's authentication domain. For more information, refer to the following topics:

Enhanced Access Administration API: Get user environment information

Enhanced Access Administration API: Grant a user access to an environment

Enhanced Access Administration API: Update environment information for a user

Enhanced Access Administration API: Get users for a specified environment

Enhanced Access Administration API: Remove a user's access to an environment

API keys can be granted all or a subset of the parent user's roles. By default, each key-pair has the same role as its parent user. If a role is revoked from the parent user, it is also revoked from the associated API keys. You can update the roles granted to a key-pair any time.

The following conditions must be met to assign a role to an API key:

• The user should have the role in the environment.
• The role should be locally granted to the user. The role should not be assigned by the user's Identity Provider (IdP) or single sign-on (SSO).
• The environment in which the role is granted should belong to the user's authentication domain. API keys can only access the environments that belong to the parent user's authentication domain.

Parent users can manage their API keys. Additionally, TBMAs can manage the API keys for users in their authentication domain.

You can manage the API keys from the Legacy Access Administration page in Enhanced Access Administration. You can also modify user information using the Enhanced Access Administration API. For more information about the API, refer to the following topics:

Enhanced Access Administration API: Create a user

Enhanced Access Administration API: Update user

Enhanced Access Administration API: Get user information

Enhanced Access Administration API: Get domain users

Enhanced Access Administration API: Delete user

Yes.

You can use a service account if you want to use Platform API or Uploader Service APIs for data transport. To create a service account, follow the steps described in the Manage users topic. Note the following:

• Specify a username that reflects the purpose of the service account.
• Make sure that the full name clearly indicates the user as a service account (for example, Apptio API Service Account).
• Make sure that the email address ends with the email domain of your company (for example, apptio_api@mycompany.com).The email address does not need to match the username. You can instead enter a real person's email address (or a distribution list). This email is rarely used outside of specific events (for example, password reset).
• Leave the Account Type field set to Standard. Although, a service account option is available, it is not necessary for API keys and is not recommended.
• Assign appropriate roles to the service account. Note the following:
  • Do not assign the Admin role to the service account.
  • If you are using the Platform API or Uploader Service API, the Power User role provides all permissions necessary to download and upload data from Costing & Planning products. You can create a custom role to limit access in a more granular way. This would involve copying the Power User role, modifying it to restrict access, and testing it as you validate the settings.
  • If you are using the Datalink (Classic) API, use the Datalink role.

The service account that you create does not have a password because API Keys are used for authentication. This is the most secure method of authenticating the use of APIs within Apptio. Once you have created a service account, follow the steps described in the section Create and manage Enhanced Access Administration API keys to create an API key pair.

Authentication & Restriction Settings

Are other types of API authentication supported, for example, JSON Web Tokens (JWT)?

Apptio's Cloudability solutions support a number of different authentication methods. For more information, refer to Rightsizing End Points. Additional authentication methods are described in the following connector guides:

Google Cloud Platform Connector Guide

Microsoft Azure Advisor Connector Guide

Microsoft Office 365 Graph Connector Guide

REST Service Connector Guide

ServiceNow REST Connector Guide

The Costing & Planning solutions only support API keys and basic authentication. For Costing & Planning solutions, we strongly recommend using API keys for authentication.

No, we cannot restrict access to any Apptio environments or systems within a specific IP range.

Apptio SaaS solutions, including Cloudability, utilize API-based connections and data ingestion. Apptio products and solutions do not require or support direct connections to client’s data centers.

Yes, there is an audit log of API access. However, it is restricted to Apptio’s internal engineering teams for data security. If you want assistance to review the API access logs or have token leakage concerns, submit a support case to escalate it to the appropriate teams for investigation.

This can occur in the following scenarios:

• User roles in the environment are granted by the Identity Provider (IdP) or single sign-on (SSO).
• Roles cannot be revoked for a user if they are associated with an API key. SSO-granted roles are not managed in Enhanced Access Administration. Therefore, API keys cannot be granted to the environments where roles are granted by the IdP for the user. In this case:
  • The environment does not belong to the same authentication domain as the user.
  • A user can be granted access (assigned roles) to an environment in any authentication domain. For security reasons, programmatic access to environments that do not belong to the user’s authentication domain is prohibited.

Service account credentials do not expire; consequently, users may continue to access Apptio even if they are no longer authorized. API keys are instead attached to a parent account to allow administrators to easily deactivate or delete individual accounts or API keys as needed, thus stopping any further interactions. We recommend that you use API keys in Apptio products for better security, traceability, and manageability of your programs and scripts.

Generic accounts are not attached to a particular individual, and hence do not provide good traceability when reviewing user activity. Furthermore, password policy rules still apply to generic accounts, which can result in account credentials expiring after 90 days. If a generic account expires, it can cause your periodic tasks to start failing. Because the generic account is not tied to a particular person, it is possible that no one would be informed of the account’s expiration and any failed tasks as a result.