Set workload identity

Turn workload identity on or off for a service, so it can exchange a short-lived token for AWS, Google Cloud or Azure credentials instead of storing cloud keys.

PUT/api/services/{id}/workload-identityHTTPS

Request & response examples

Request exampleServer-side

curl --fail-with-body --request PUT \
  'https://app.helicarrier.xyz/api/services/YOUR_ID/workload-identity' \
  -H "Authorization: Bearer $HELI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "enabled": true,
  "audience": "sts.amazonaws.com"
}'

const response = await fetch(
  "https://app.helicarrier.xyz/api/services/YOUR_ID/workload-identity",
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.HELI_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "enabled": true,
      "audience": "sts.amazonaws.com"
    })
  }
);
const data = await response.json();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${data.error}`);
}
// Inspect data; avoid logging secret responses.

import os
import requests

response = requests.request(
    "PUT",
    "https://app.helicarrier.xyz/api/services/YOUR_ID/workload-identity",
    headers={
        "Authorization": f"Bearer {os.environ['HELI_API_KEY']}"
    },
    json={
      "enabled": True,
      "audience": "sts.amazonaws.com"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
# Inspect data; avoid logging secret responses.

Response example200

{
  "enabled": true,
  "issuer": "https://app.helicarrier.xyz/oidc/svc_example",
  "subject": "account:acct_example:project:prj_example:service:svc_example:env:env_example",
  "audience": "sts.amazonaws.com",
  "ttlSeconds": 900,
  "tokenPath": "/var/run/heli/oidc-token",
  "note": "redeploy the service to mount /var/run/heli; after that the token refreshes on its own"
}

Illustrative values · selected fields

Response details OpenAPI

Authorization

An account key with access to the resource. Project and service keys do not authorize this operation.

Authorization: Bearer <key>Key setup

Path parameters

idstringrequired

Service id.

Request bodyapplication/json

enabledbooleanrequired

true to turn it on, false to turn it off.

audiencestringoptional

The audience your cloud expects: sts.amazonaws.com, api://AzureADTokenExchange, or your GCP provider's audience.

ttlSecondsintegeroptional

Token lifetime, 300-3600 (default 900).

Response 200

Turning it on returns the issuer, subject and audience to trust; redeploy the service to mount the token. Turning it off returns enabled: false and removes the token file. Anyone who can change what the service runs can read its token, so deploy access to the service is access to the cloud role that trusts it.

Examples show selected response fields with illustrative values. Your response can contain additional fields.

enabledboolean

issuerstring

subjectstring

audiencestring

ttlSecondsinteger

tokenPathstring

notestring

Additional information about the result; can be empty.

Errors

400

Invalid parameters. Check the required fields, types, and resource configuration.

401

The API key is missing, invalid, or revoked.

403

The caller or key scope does not permit this operation.

409

The current resource state prevents the operation. Inspect it before retrying.

500

The operation could not be completed. Check resource state before retrying a write.

503

The request could not be completed.

Error handling and safe retries

ALSO AVAILABLE VIA MCP

`set_workload_identity`

Required MCP arguments: id, enabled. Send path, query, and body fields together as tool arguments.

Connect your agent

curl --fail-with-body --request PUT \ 'https://app.helicarrier.xyz/api/services/YOUR_ID/workload-identity' \ -H "Authorization: Bearer $HELI_API_KEY" \ -H 'Content-Type: application/json' \ --data '{ "enabled": true, "audience": "sts.amazonaws.com" }'

import os import requests response = requests.request( "PUT", "https://app.helicarrier.xyz/api/services/YOUR_ID/workload-identity", headers={ "Authorization": f"Bearer {os.environ['HELI_API_KEY']}" }, json={ "enabled": True, "audience": "sts.amazonaws.com" }, timeout=30, ) response.raise_for_status() data = response.json() # Inspect data; avoid logging secret responses.

{ "enabled": true, "issuer": "https://app.helicarrier.xyz/oidc/svc_example", "subject": "account:acct_example:project:prj_example:service:svc_example:env:env_example", "audience": "sts.amazonaws.com", "ttlSeconds": 900, "tokenPath": "/var/run/heli/oidc-token", "note": "redeploy the service to mount /var/run/heli; after that the token refreshes on its own" }