credctl auth

Synopsis

credctl auth [flags]

Description

credctl auth signs a JWT with the hardware-bound Secure Enclave key and exchanges it for short-lived AWS STS credentials via AssumeRoleWithWebIdentity. Touch ID prompts you to authorise the signing operation.

The default output format (credential_process) is compatible with the AWS CLI and SDKs. Add it to ~/.aws/config for transparent credential retrieval:

[profile credctl]
credential_process = credctl auth

Progress messages are written to stderr. Credential output goes to stdout.

Flags

Flag	Type	Default	Description
--format	string	credential_process	Output format: credential_process or env

Examples

Default output (credential_process format)

credctl auth

{
  "Version": 1,
  "AccessKeyId": "ASIAI...",
  "SecretAccessKey": "...",
  "SessionToken": "...",
  "Expiration": "2026-03-04T12:30:00Z"
}

Stderr output:

Signing JWT with Secure Enclave...
Requesting temporary credentials from AWS STS...
Credentials valid until 2026-03-04T12:30:00Z

Environment variable export format

credctl auth --format env

export AWS_ACCESS_KEY_ID=ASIAI...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...

Use with eval to set credentials in your current shell:

eval $(credctl auth --format env)
aws s3 ls

Exit codes

Code	Meaning
0	Credentials retrieved successfully
1	Error (device not initialised, AWS not configured, STS failure, or other error)

See also

• credctl setup aws — set up the AWS infrastructure credctl auth requires
• credctl status — check device identity health
• AWS setup guide — credential helper configuration
• Troubleshooting — authentication error solutions