Skip to main content

API Keys

API Keys provide a secure way for external systems, such as CI/CD pipelines and automation scripts, to interact with the ImageFactory API. Unlike user accounts that rely on interactive OIDC login, API keys use a static secret for authentication.

API Key Properties​

Each API key in ImageFactory has the following attributes:

  • ID: A unique identifier for the key (e.g., ak_123456789).
  • Name: A descriptive label to help you identify the key's purpose.
  • Secret: A cryptographically secure string used for authentication.

The Secret Lifecycle​

When you create an API key, the system generates a secret and returns it in the response.

CRITICAL: The secret is only shown once at the time of creation. ImageFactory does not store the secret in plain text, and it cannot be retrieved later. You must store the secret securely in a password manager or a secret vault (like AWS Secrets Manager or Azure Key Vault) immediately after creation.

Authentication Methods​

You can use an API key to authenticate requests in two ways.

1. Custom Header​

Include the secret in the x-api-key header of your HTTP request.

curl -X POST https://api.imagefactory.nordcloudapp.com/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_SECRET" \
  -d '{"query": "{ templates { id name } }"}'

2. Authorization Header​

Alternatively, you can pass the secret as a Bearer token in the standard Authorization header.

curl -X POST https://api.imagefactory.nordcloudapp.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY_SECRET" \
  -d '{"query": "{ templates { id name } }"}'

Scoping and Permissions​

API keys are scoped to the customer environment where they were created. They cannot access resources belonging to other customers.

By default, a newly created API key has no permissions. To grant access, you must create a Role Binding that connects the API key's ID to a specific Role.

  1. Create the API key and note its ID.
  2. Identify or create a Role with the required permissions.
  3. Create a Role Binding with kind: API_KEY, subject: KEY_ID, and the target roleId.

Common Use Cases​

CI/CD Pipelines​

Automate your golden image lifecycle by integrating ImageFactory into your deployment pipelines.

  • Trigger Rebuilds: Start a new image build when a custom component script is updated in your repository.
  • Status Checks: Poll the API to verify if a build has completed successfully before proceeding with deployment.
  • Compliance Verification: Retrieve compliance scores and SBOM data to ensure images meet security standards before they are used in production.

Managing API Keys​

To manage API keys, navigate to Permissions in the sidebar and select the API Keys tab. From here you can create new keys, view existing keys, and delete keys that are no longer needed.

Important: When you create a new API key, the secret is displayed only once. Copy and store it securely before closing the dialog.

For a detailed walkthrough, see the Permissions guide.

Via API

API keys can also be managed programmatically through the GraphQL API.

Creating an API Key​

mutation CreateApiKey($input: CreateApiKeyInput!) {
  createApiKey(input: $input) {
    id
    name
    secret
  }
}

Variables:

{
  "input": {
    "name": "GitHub-Actions-Builder"
  }
}

Listing API Keys​

You can list all API keys for the current customer to review active programmatic access.

query ListApiKeys {
  apiKeys {
    id
    name
    createdAt
  }
}

Deleting an API Key​

If a key is compromised or no longer needed, delete it immediately to revoke access.

mutation DeleteApiKey($id: ID!) {
  deleteApiKey(id: $id)
}

Best Practices​

  • Rotate Keys Regularly: Periodically delete old keys and create new ones to minimize the impact of potential leaks.
  • Least Privilege: Create specific roles for automation tasks (e.g., a "Builder" role that can only create and view templates) rather than using an admin role.
  • One Key Per System: Use separate API keys for different tools or teams. This makes it easier to audit activity and revoke access without affecting other systems.
  • Secure Storage: Never hardcode API key secrets in source code or configuration files. Use environment variables or secret management services.