Credentials

Manage cloud credentials securely — secrets are stored in a vault, not in the database.

Credential configs store the authentication information Forgecroft needs to interact with cloud providers. Secrets are stored separately from metadata in a secure vault.

Credential Types

Type	Required Fields	Use Case
`aws_static`	`access_key_id`, `secret_access_key`	AWS with static IAM credentials
`aws_assume_role`	`role_arn`	AWS with IAM role assumption
`gcp_service_account`	Service account key JSON	GCP with service account
`cloudflare_api_token`	API token	Cloudflare
`generic_env`	Arbitrary key-value pairs	Any provider with env var auth

Creating Credentials

Create the credential config (metadata only):

POST /credential-configs
{
  "name": "Production AWS",
  "credential_type": "aws_static",
  "project_id": "project-uuid"
}

Store the secrets separately:

POST /credential-configs/{id}/secrets
{
  "data": {
    "access_key_id": "AKIA...",
    "secret_access_key": "..."
  }
}

For generic_env type, key names must be valid environment variable names (start with letter or underscore, then alphanumeric or underscore).

Scoping

Credentials can be scoped to:

Organization level — available to all workspaces
Project level — available only to workspaces within a specific project

When attaching credentials to a workspace, they must belong to the same org, and project-scoped credentials must belong to the workspace’s parent project.

Verifying Credentials

Test that stored credentials are valid:

POST /credential-configs/{id}/verify

This calls the provider’s API to check validity. Response:

{ "valid": true, "identity": "arn:aws:iam::123456789:user/deploy" }
// or
{ "valid": false, "error": "InvalidClientTokenId" }

Note: A failed verification returns 200 with valid: false, not an error status. If no credentials are stored, it returns 422.

Attaching to Workspaces

Attach credentials via credential_config_ids on the workspace:

PATCH /workspaces/{id}
{ "credential_config_ids": ["cred-uuid-1", "cred-uuid-2"] }

This is a full replacement — all existing credential links are removed and replaced with the new list.

Deleting Credentials

Deleting a credential config also deletes its secrets from the vault. Returns 409 if any workspaces still reference the credential.