Programmatic Access to Your Infrastructure Operations
Build custom workflows, integrations, and automation with the Terrateam REST API. Full programmatic control over installations, repositories, the key-value store, and more.
What you can do with the API
Access Token Management
Create, list, and revoke API tokens with fine-grained capability controls. Define exactly what each token can do.
Key-Value Store
Store artifacts and build outputs between plan and apply runs. Lambda packages, compiled binaries, or any data needed across operations.
VCS Integrations
Manage GitHub and GitLab installations, repositories, pull requests, and work manifests programmatically.
Stack Information
Retrieve stack details and dependencies for any pull request. Build custom reporting or monitoring integrations.
System Configuration
Access server configuration, OAuth client IDs, and manage long-running async tasks.
Query Infrastructure
Query dirspaces, retrieve outputs, list workspaces, and access work manifests for complete visibility.
Security-first authentication
A two-step authentication model that balances security with developer experience
Create API Key
Create a long-lived API key in the dashboard with specific capabilities for your integration needs.
Settings → API Access → Create Token
Get Access Token
Use your API key to obtain short-lived access tokens (60 seconds) that inherit your capabilities.
POST /api/v1/access-token/refresh
Make API Calls
Use the short-lived access token in the authorization header for all your API requests.
Authorization: Bearer <token>
Why short-lived tokens?
Your long-lived API key never touches production systems. Access tokens expire after 60 seconds, so compromised tokens become useless quickly. This approach minimizes risk while maintaining ease of use.
Fine-grained capabilities
Grant exactly the permissions each integration needs, nothing more
KV Store Access
Separate read and write permissions for the key-value store
- Read from KV store
- Write to KV store
Token Management
Create new API tokens programmatically for automation
- Create access tokens
- List and revoke tokens
Installation Scopes
Scope tokens to specific GitHub or GitLab installations
- Per-installation access control
- VCS-specific permissions
Principle of Least Privilege
Combine capabilities to create tokens with precisely the access your automation requires
- Minimal permission grants
- Easy audit trail
Get started in minutes
Creating your first API integration is straightforward
Example: Refresh token and make API call
#!/bin/bash API_KEY="your_api_key_here" # Get access token ACCESS_TOKEN=$(curl -s -X POST \ https://app.terrateam.io/api/v1/access-token/refresh \ -H "Authorization: Bearer $API_KEY" | jq -r '.token') # Make API call curl -X GET https://app.terrateam.io/api/v1/whoami \ -H "Authorization: Bearer $ACCESS_TOKEN"
Token Expiration
Access tokens expire after 60 seconds. For long-running scripts, refresh tokens every 50 seconds to ensure continuous access.
Common use cases
Custom CI/CD Integrations
Integrate Terrateam into your existing CI/CD pipelines. Query infrastructure state, check work manifests, and retrieve operation results programmatically.
Artifact Storage Between Runs
Use the KV store to persist artifacts like Lambda packages or build outputs between plan and apply runs.
Custom Reporting & Analytics
Build dashboards and reports by querying work manifests, stack dependencies, and infrastructure state.
Automated Orchestration
Orchestrate complex workflows across repositories and installations with programmatic control over operations.
Complete schema documentation
Every endpoint includes full JSON schema documentation for requests and responses. No guessing, no trial-and-error. Just clear, comprehensive documentation.
Build custom integrations with the Terrateam API
Automate infrastructure operations, integrate with your existing tools, and build workflows that match your team's needs.
Ready to get started?
The Terrateam REST API opens up new possibilities for infrastructure automation. Build the integrations and workflows you need.