Skip to main content

How to Use Ephemeral API Keys in Building Blocks

What is this guide about?

This guide explains how to configure ephemeral API keys for building blocks. Ephemeral API keys allow your building blocks to interact with the meshStack API during their execution, enabling advanced automation patterns like creating nested building blocks, managing tenants, or updating other meshObjects, all without requiring admin permissions.

Challenge​

You want to create a building block that provisions infrastructure and also needs to interact with meshStack during its execution. For example, your building block might need to:

  • Create additional building blocks
  • Update project or tenant tags
  • Query workspace information
  • Create tenants as part of a complex provisioning workflow

Traditionally, this would require manually managing API credentials and giving the building block broad admin access to the required resources. Ephemeral API keys solve this by providing short-lived, automatically managed credentials scoped to only the consuming workspace and the permissions your building block actually needs.

Prerequisites​

  • Admin permissions or workspace manager/owner permissions on the workspace that owns the building block definition
  • A building block definition using one of the supported implementation types:
    • OpenTofu
    • GitLab CI/CD
    • Azure DevOps Pipelines
  • Understanding of which meshStack API permissions your building block needs
GitHub Actions and Azure DevOps Not Supported Yet

Ephemeral API keys are not yet fully supported for GitHub Actions and Azure DevOps building blocks. If you need API access in such a building block, use standard workspace API keys as described in How to Manage API Keys.

Step-by-Step Guide​

Step 1: Identify Required Permissions​

Before configuring ephemeral API keys, identify which meshStack API permissions your building block needs. Common use cases include:

Use CasePermissions Needed
Create nested building blocksBuilding Block (write), Building Block Definition (read)
Read workspace informationWorkspace (read)
Manage projectsProject (read, write, delete)
Manage tenantsTenant (read, write, delete)
Read event logsEvent Log (read)
Principle of Least Privilege

Only select the permissions your building block actually needs. The ephemeral API key is scoped to the workspace where the building block is provisioned, so you don't need to worry about cross-workspace access.

Step 2: Configure Permissions on the Building Block Definition​

  1. Navigate to Platform Builder > Building Blocks > Definitions
  2. Select your building block definition (or create a new one)
  3. If editing an existing definition, click Create draft to start a new version
  4. Go to the Implementation tab
  5. Scroll to the Ephemeral API Keys section
  6. Select the required permissions from the dropdown

The UI shows a grouped list of available permissions organized by resource type (e.g., Building Block, Project, Tenant). Select all permissions your building block requires.

Step 3: Save and Release the Definition​

After configuring permissions, save the building block definition version

meshStack automatically adds two system-generated inputs to your building block definition:

  • MESHSTACK_ENDPOINT: The meshStack API URL
  • MESHSTACK_API_TOKEN: A placeholder that will be replaced with the actual token at runtime
Auto-Generated Inputs

You don't need to manually create these inputs. They appear automatically when you configure permissions. For OpenTofu building blocks, these inputs are provided as environment variables that the meshStack Terraform provider automatically uses for authentication.

When you have successfully tested your new building block definition, click Release to publish the new version.

Step 4: Use the API Token in Your Building Block Code​

OpenTofu Building Blocks​

For OpenTofu building blocks, the meshStack Terraform provider automatically uses the MESHSTACK_API_TOKEN and MESHSTACK_ENDPOINT environment variables. No additional configuration is needed:

terraform {
  required_providers {
    meshstack = {
      source  = "meshcloud/meshstack"
      version = ">= 0.17.3"
    }
  }
}

# Provider automatically authenticates using MESHSTACK_API_TOKEN
provider "meshstack" {}

# Example: Create a nested building block
resource "meshstack_building_block_v2" "example_workspace" {
  spec = {
    building_block_definition_version_ref = {
      uuid = "00000000-0000-0000-0000-000000000000" # Replace with actual definition version UUID
    }

    display_name = "my-building-block"
    target_ref = {
      kind       = "meshWorkspace"
      identifier = "my-workspace-identifier" # Replace with actual workspace identifier
    }

    inputs = {
      name = { value_string = "my-name" }
      size = { value_int = 16 }
    }
  }
}

GitLab CI/CD​

For pipeline-based building blocks, access the token via environment variables:

# GitLab CI/CD example
my_job:
  script:
    - |
      curl -X GET "${MESHSTACK_ENDPOINT}/api/meshobjects/meshprojects" \
        -H "Authorization: Bearer ${MESHSTACK_API_TOKEN}" \
        -H "Accept: application/vnd.meshcloud.api.meshproject.v3.hal+json"

Step 5: Verify Permissions in the Marketplace​

After releasing the building block definition, verify that users see the correct permissions:

  1. Navigate to the marketplace
  2. Find your building block definition
  3. Check the Permissions section

Users see a list of permissions the building block will receive on their workspace. This transparency helps users make informed decisions before adding the building block.

Understanding API Key Lifecycle​

Ephemeral API keys have a defined lifecycle:

  1. Creation: When a building block run starts, meshStack creates an ephemeral API key with the configured permissions, scoped to the consuming workspace
  2. Usage: The API key is valid during the building block run execution
  3. Deletion: The API key is automatically deleted when:
    • The run reaches a terminal state (succeeded or failed), OR
    • 6 hours have elapsed (maximum lifetime)

This lifecycle ensures credentials are short-lived and automatically cleaned up, reducing security risks.

Handling Privilege Escalation​

If your building block creates nested building blocks that also have permission requirements, meshStack enforces privilege escalation prevention:

  • A nested building block can only have permissions that are a subset of (or equal to) the parent building block's permissions
  • If a nested building block requests more permissions than the parent has, the creation fails with an error

This ensures building blocks cannot grant themselves elevated access through nested automation.

Troubleshooting​

API Token Not Working​

  • Verify the building block run is still active (tokens expire when runs complete)
  • Check that the required permissions are configured on the definition
  • Ensure you're using the token in the correct workspace context

Missing MESHSTACK_API_TOKEN Input​

  • Permissions must be configured on the building block definition version
  • Save the building block definition after adding permissions
  • The system inputs are auto-generated only when permissions are configured

Nested Building Block Creation Fails​

  • Check if the nested definition requires more permissions than the parent has
  • Review the error message for details about which permissions are missing
  • Ensure the parent building block has all permissions the nested building block needs

Concepts​

Guides​