Configuration reference

Overview

credctl stores device identity and cloud provider configuration in a single JSON file:

~/.credctl/config.json

This file is created by credctl init and updated by credctl setup aws. File permissions are 0600 (user read/write only).

Example configuration

{
  "version": 1,
  "device_id": "SHA256:aBcDeFg...",
  "key_tag": "com.crzy.credctl.device-key",
  "created_at": "2026-03-02T10:00:00Z",
  "enclave_type": "secure_enclave",
  "public_key_path": "~/.credctl/device.pub",
  "aws": {
    "role_arn": "arn:aws:iam::123456789012:role/credctl-device-role",
    "issuer_url": "https://d1234567890.cloudfront.net",
    "region": "us-east-1",
    "s3_bucket": "credctl-oidc-123456789012"
  }
}

Top-level fields

Field	Type	Required	Default	Description
version	integer	Yes (auto-generated)	1	Configuration schema version.
device_id	string	Yes (auto-generated)	—	SHA-256 fingerprint of the device public key. Set by credctl init.
key_tag	string	Yes (auto-generated)	com.crzy.credctl.device-key	Keychain application tag for the Secure Enclave key. Override with credctl init --key-tag.
enclave_type	string	Yes (auto-generated)	—	Hardware type. Currently secure_enclave only. tpm support planned for a future release.
created_at	string (RFC 3339)	Yes (auto-generated)	—	Timestamp of device identity creation.
public_key_path	string	Yes (auto-generated)	~/.credctl/device.pub	Path to the exported public key PEM file.
aws	object	No	—	AWS configuration block. Set by credctl setup aws. See below.

Note

Auto-generated fields are set by credctl init and should not be manually edited. There is no multi-profile system — credctl supports a single device identity and a single AWS configuration.

AWS configuration fields

The aws block contains the configuration for OIDC federation with AWS. These fields are set automatically by credctl setup aws.

Field	Type	Required	Default	Description
role_arn	string	Yes	—	IAM role ARN to assume via AssumeRoleWithWebIdentity. Must match arn:aws:iam::\d{12}:role/.+
issuer_url	string	Yes	—	OIDC issuer URL (the CloudFront distribution URL). Must be a valid HTTPS URL.
region	string	No	—	AWS region for the STS endpoint. Must be a valid AWS region code (e.g., us-east-1).
s3_bucket	string	No	—	S3 bucket name where OIDC documents are published.

• Credential TTL is determined by the IAM role’s maximum session duration, not by credctl configuration.
• GCP and Azure configuration blocks will be added in future releases.

File permissions

Path	Permissions	Notes
~/.credctl/	0700	Directory — user access only
~/.credctl/config.json	0600	Configuration — user read/write only
~/.credctl/device.pub	0644	Public key — safe to share
~/.credctl/oidc/	0700	OIDC documents directory

File layout

~/.credctl/
├── config.json                     # Device and AWS configuration (0600)
├── device.pub                      # Public key PEM (0644)
└── oidc/                           # OIDC discovery documents (0700)
    ├── .well-known/
    │   └── openid-configuration    # OIDC discovery document
    └── keys.json                   # JWKS (JSON Web Key Set)

Managing configuration

• credctl setup aws — sets up AWS infrastructure and writes the aws configuration block (preferred method)
• credctl oidc generate / credctl oidc publish — manage OIDC documents independently
• Manual editing is possible but not recommended (risk of malformed JSON or incorrect values)
• There are no credctl config subcommands — configuration is managed via setup aws or manual editing

Related

• credctl setup aws — automated AWS setup
• credctl init — device identity creation
• AWS setup guide — configuring AWS OIDC federation
• Troubleshooting — configuration error solutions