Skip to main content

API Keys

Appcircle provides a secure method to create and manage API keys for accessing its API. These tokens can be generated and scoped to match organizational requirements.

Creating an API Key​

To generate a new API key:

1. Click on the Create a New API Key button.

Screenshot

2. Enter a name for your API key and select an expiry date.
Note: The expiry date and API key name cannot be modified after creation.

Screenshot

3. Select the Organization and the Roles that the API key should have access to.

Screenshot

4. Once the key is created, the API key secret will be shown only once. Copy and store it securely. After this, it will be encrypted and hidden. However, users can create a new key with the same expiry date if needed.

Screenshot

Managing API Keys​

You can view all your API keys under the API Keys section. The status of each key is indicated as either Active or Expired.

  • Manage: Allows updating the role scope of the API key.
    Note: Updating roles does not require regenerating the API key or secret.

  • Delete: Permanently removes the API key from the system.

Screenshot
  • Each API key includes an auto-generated email used for audit logging purposes.
tip

This feature is also available for sub-organizations.

Using API Keys to Retrieve Access Tokens​

The following script can be used to retrieve an access token using an API key name and secret. You also need to include the Organization ID:

set -e

API_KEY_NAME=apikey1
API_KEY_SECRET='your_secret'
ROOT_ORGANIZATION_ID=your_orgID # root_org
SUB_ORGANIZATION_ID=your_orgID # sub_org

echo "Retrieving access token for API key: $API_KEY_NAME"

response=$(curl --location 'https://auth.appcircle.io/auth/v1/api-key/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name='"$API_KEY_NAME"'' \
--data-urlencode 'secret='"$API_KEY_SECRET"'' \
--data-urlencode 'organizationId='"$SUB_ORGANIZATION_ID"'')

ACCESS_TOKEN=$(echo "$response" | jq -r '.access_token')

echo "Access token retrieved: $ACCESS_TOKEN"
tip

An access token for a sub-organization can be created using an API key generated within the root organization, provided that the role settings include access to these sub-organizations.

API Key Limit

The overall API key limit is typically 10 keys, including those from both the root and sub-organizations.