> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Operator Identity (BYOK)

> The AWS identity KnoxCall uses to assume customer KMS roles for Bring-Your-Own-Key — an IAM user with sts:AssumeRole scoped to BYOK role ARNs and nothing else, and how it differs from the master-key unseal identity.

# AWS Operator Identity (BYOK)

When a workspace brings its own AWS KMS key ([tenant KMS setup](/essentials/tenant-kms/setup-aws)), KnoxCall does not hold that workspace's AWS credentials. It holds **one identity of its own** and assumes the role the workspace created, and the workspace's key policy trusts exactly that identity. This card is that identity.

**Scope: Global defaults** only. On KnoxCall Cloud it is KnoxCall's; the BYOK wizard shows workspaces the principal to trust. A self-hosted deployment that offers BYOK to its workspaces configures its own here.

<Warning>
  This is **not** the master-key unseal identity. Rotating or deleting it cannot lock the deployment out of its master key; it affects only workspaces' BYOK operations.
</Warning>

## 1. In AWS IAM

1. **IAM → Users → Create user**, no console access.
2. Attach an inline policy with exactly two actions:

```json theme={"dark"}
{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "sts:GetCallerIdentity", "Resource": "*" },
    { "Effect": "Allow", "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::*:role/knoxcall-byok-*" }
  ]
}
```

`GetCallerIdentity` lets KnoxCall display which principal workspaces should trust. `AssumeRole` is restricted by resource to the BYOK role naming pattern — never `*`. **No `kms:*` on this identity**: KMS permissions are granted by each workspace to the *assumed* role, which is the whole point of BYOK.

3. **Security credentials → Create access key → Application running outside AWS**. Copy both halves.

## 2. Enter it in KnoxCall

**Settings → Integrations → Global defaults → AWS operator identity (BYOK)** → *Configure*:

| Field                           | Value            |
| ------------------------------- | ---------------- |
| **Access key ID**               | `AKIA…`          |
| **Secret access key**           | The secret half  |
| **Default region** *(optional)* | e.g. `us-east-1` |

**Save credentials.**

## 3. Verify

Open a workspace's **Settings → Security → Tenant master key** and start the AWS BYOK wizard: it shows the resolved principal (a `GetCallerIdentity` call with this identity). Completing a BYOK setup end-to-end proves `AssumeRole`.

## Things that bite

* **When no row is stored, the AWS SDK default chain is used** (environment, shared config, instance metadata) — so "not configured" does not mean "no AWS identity in play" on a self-hosted host.
* **Rotation is two-sided only in one direction.** Workspaces trust the *user's ARN*, not its key, so rotating the access key needs no change on their side; deleting the user does.

## Related

* [BYOK and KMS](/essentials/key-management/byok-and-kms)
* [Tenant KMS — AWS setup](/essentials/tenant-kms/setup-aws)