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 cloud credentials. Touch ID prompts you to authorise the signing operation.

Supports AWS (default) and GCP via the --provider flag.

If the credential daemon is running, credctl auth returns cached credentials instantly without Touch ID. If the daemon is not running, it falls back to the normal direct path. This is transparent — no flags or configuration changes needed.

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

Flags

Flag	Type	Default	Description
--provider	string	aws	Cloud provider: aws or gcp.
--format	string	varies	Output format. AWS: credential_process (default) or env. GCP: executable (default) or env.

AWS examples

Default output (credential_process format)

credctl auth

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

Configure as an AWS credential process:

[profile credctl]
credential_process = credctl auth

credctl setup aws configures this automatically.

Environment variable export

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

GCP examples

Default output (executable format)

credctl auth --provider gcp

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:jwt",
  "expiration_time": 1709800300,
  "subject_token": "eyJhbGciOiJFUzI1NiIs..."
}

This format is used by GCP client libraries via the credential config file generated by credctl setup gcp.

Environment variable export

eval $(credctl auth --provider gcp --format env)
gcloud storage ls

Sets CLOUDSDK_AUTH_ACCESS_TOKEN with a short-lived OAuth2 access token. This format does the full two-step exchange (STS + service account impersonation) within credctl.

Exit codes

Code	Meaning
0	Credentials retrieved successfully
1	Error (device not initialised, cloud provider not configured, exchange failure, or other error)

See also

• credctl daemon — credential caching daemon (experimental)
• credctl setup aws — set up AWS OIDC federation
• credctl setup gcp — set up GCP Workload Identity Federation
• credctl status — check device identity health
• AWS setup guide — AWS credential helper configuration
• GCP setup guide — GCP credential helper configuration
• Troubleshooting — authentication error solutions