# Deploy and manage a Nitro API Signer

Complete [Prepare AWS](/developers/getting-started/set-up-an-api-signer/api-signer-aws-enclave-prerequisites), then follow the
wizard and deployment steps below. Activation is automatic after mobile approval;
no signer ID or post-registration stack update is needed.

## Open the Fordefi setup wizard

1. Sign in as an administrator to the intended Fordefi environment and organization.
2. In the web console, go to **Settings > API Signer** and select **AWS Nitro Enclave**.

3. In **Getting started**, click **Get started**.

4. Leave the wizard at **Deploy the API signer** while you complete the AWS steps below.


## Download the release

Download the production TAR from [Fordefi JFrog](https://fordefi.jfrog.io):
`generic/api-signer-nitro/<version>/production/`. This guide uses
[2026.11.03.015+e4a583fd](https://fordefi.jfrog.io/artifactory/generic/api-signer-nitro/2026.11.03.015/production/fordefi-api-signer-nitro-production-2026.11.03.015+e4a583fd.tar.gz).
It includes the CLI, template, and runtime files. The package fixes the Fordefi
environment; a staging TAR cannot deploy a production signer.

Extract and verify on your trusted workstation:

```sh
tar -xzf fordefi-api-signer-nitro-production-2026.11.03.015+e4a583fd.tar.gz
cd fordefi-api-signer-nitro-production-2026.11.03.015+e4a583fd
sha256sum -c SHA256SUMS
```

On macOS, use `shasum -a 256 -c SHA256SUMS`. All checks must pass. Leave the
inner `api-signer-nitro.tar.gz` intact.

## Deploy the signer

Keep a single signer instance
The template sets the Auto Scaling group's minimum, desired, and maximum capacity
to `1`. Never increase these values above `1` or launch another instance against
the same signer state. Multiple active copies of one signer are not supported.

To configure concurrent signing workers (default: `1`), add `--threads <positive-integer>`
to the CLI command or set the CloudFormation `Threads` parameter. This option
requires a release with thread-count support.

Choose one method from the extracted release directory:

Packaged CLI (recommended)
### Option 1: Packaged CLI

```sh
python3 deploy.py \
  --profile '<customer-profile>' \
  --account-id '<12-digit-account-id>' \
  --region '<deployment-region>' \
  --stack-name fordefi-api-signer \
  --vpc-id '<vpc-id>' \
  --subnet-id '<private-subnet-id>' \
  --ami-id '<amazon-linux-2023-x86-64-ami-id>' \
  --instance-type m6i.xlarge \
  --key-administrator-arn '<deployment-IAM-role-ARN>'
```

The CLI checks the account/checksums, creates the stack, uploads release files,
and starts the signer. If using a CloudFormation execution role, add
`--role-arn '<execution-role-ARN>'` and another `--key-administrator-arn` for it.

Wait for completion. The CLI exports `provisioning-public-key.pem` from KMS and
prints its fingerprint and Fordefi environment. Continue to
[link and activate](#register-and-activate-in-fordefi).

CloudFormation console
### Option 2: CloudFormation console

1. In your AWS account and region, create stack `fordefi-api-signer` using
`ApiSignerNitro.template.json`.
2. Enter the [parameters](/developers/getting-started/set-up-an-api-signer/api-signer-aws-enclave-prerequisites#deployment-parameters).
Keep `EnableRuntime=false` and the release/environment defaults. Under
permissions, select an execution role only if required; otherwise your
signed-in identity is used. Include that principal in `KeyAdministratorArns`.
3. Acknowledge IAM resource creation, create the stack, and wait for `CREATE_COMPLETE`.
4. [Upload the release files](#upload-release-files). Both uploads must succeed.
5. Update the same stack with its existing template: set only `EnableRuntime=true`,
preserve other parameters, and wait for `UPDATE_COMPLETE`.
6. From **Outputs**, run `GetProvisioningPublicKeyCommand` on your trusted
workstation with the intended `AWS_PROFILE`. Convert the resulting DER file
to PEM and print its fingerprint:

```sh
openssl pkey -pubin -inform DER -in provisioning-public-key.der -out provisioning-public-key.pem
openssl dgst -sha256 -binary provisioning-public-key.der | openssl base64 -A
```
7. Continue to [link and activate](#register-and-activate-in-fordefi).


## Register and activate in Fordefi

1. Return to **Deploy the API signer** in the wizard and click **Next**.

2. At **Link your new API signer to your organization**, enter a name and paste all of
`provisioning-public-key.pem`, including `-----BEGIN PUBLIC KEY-----` and
`-----END PUBLIC KEY-----`. This is the RSA-4096 provisioning public key
exported from KMS, used to encrypt onboarding data. Click **Next**.

3. Open the activation request in the Fordefi mobile app. Compare its fingerprint
with the one printed by the CLI or manual KMS-key command on your trusted
workstation. **Approve only if they match.**
4. Keep the signer running during **Completing setup**.
5. When the wizard shows **Activate on your phone**, click **Done**.
6. In the Fordefi web console, click **Settings > API Signer**, confirm **Active** and a recent, updating
**Last seen**. Stack creation alone does not confirm successful activation.


If you select **Abort** and confirm it in the web console, you cannot reconnect
the existing deployment to a new registration. To start over, delete the
CloudFormation stack, deploy a new stack, and register using its new provisioning
public key.

To submit requests, [create an API User](/developers/getting-started/create-an-api-user) with a separate
request-signing key.

## Upgrades

Only one instance runs, so upgrades incur downtime.

Download and verify the new release, then [upload its files](#upload-release-files)
to the existing stack's bucket. Update that stack with the new template:
set `ReleaseVersion` to its new default and `EnableRuntime=true`; preserve other
parameters, including the AMI unless deliberately changing it. Do not create a
second stack against the same state. The CLI resumes initial deployment only;
it does not upgrade or reconfigure existing stacks.

Stack deletion retains KMS keys and encrypted state; a new stack does not
reattach them automatically. Contact Fordefi before recovery or deliberate destruction.

## Upload release files

For manual deployment and upgrades only; the CLI handles initial uploads.
From the extracted directory, with [`AWS_PROFILE` and `AWS_REGION`](/developers/getting-started/set-up-an-api-signer/api-signer-aws-enclave-prerequisites#deployment-parameters) set:

```sh
STACK_NAME=fordefi-api-signer
aws sts get-caller-identity
BUCKET=$(aws cloudformation describe-stacks --stack-name "$STACK_NAME" \
  --query 'Stacks[0].Outputs[?OutputKey==`StateBucketName`].OutputValue | [0]' --output text)
PREFIX="releases/$(openssl dgst -sha256 -r manifest.json | cut -d ' ' -f 1)"
test -n "$BUCKET" && test "$BUCKET" != None &&
aws s3 cp manifest.json "s3://$BUCKET/$PREFIX/manifest.json" &&
aws s3 cp api-signer-nitro.tar.gz "s3://$BUCKET/$PREFIX/api-signer-nitro.tar.gz"
```

Both uploads must succeed. The runtime can read but cannot modify these files.

## Troubleshooting

Find the log group in **CloudFormation > Outputs > RuntimeLogGroupName**.
Inspect CloudWatch streams `<instance-id>/bootstrap` and `<instance-id>/signer`;
early bootstrap failures may appear only in EC2 console output.

| Symptom | Action |
|  --- | --- |
| `GetPublicKey` access denied | Check AWS profile/account, region, key ARN, and workstation `kms:GetPublicKey` permission. |
| Provisioning key already registered | Check the original Fordefi registration and contact support. Changing stack parameters does not unregister it; removing a pending registration does not reset persisted state. |
| CloudFormation `FAILURE` signal | Check bootstrap logs for download, integrity, instance-requirement, or startup errors before retrying. |
| CLI interrupted | Rerun the same command/release. After activation rollback, fix the cause and add `--retry`. `CREATE_FAILED`, `ROLLBACK_COMPLETE`, or failed rollback requires operator recovery first. |
| Pending activation | Check mobile approval, instance status, outbound connectivity, and signer logs. |
| Nitro option missing / onboarding unsupported | Confirm the Fordefi environment and ask support about enablement. |
| Ownership or encrypted-state identity error | Contact support; do not delete state or ownership markers. |


[Contact support](mailto:support@fordefi.com) if the issue persists.