---
title: "SDK"
description: "This implementation utilizes AWS SDK's default credential provider chain for authentication, automatically detecting credentials from multiple sources including:"
stack: "Community Stack (open source) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/issuer/key-management/aws-kms/sdk
generated: 2026-07-20
---
# SDK

This implementation utilizes AWS SDK's default credential provider chain for authentication, automatically detecting
credentials from multiple sources including:

- Environment variables
- AWS credentials file
- IAM roles for EC2
- Container credentials
- SSO credentials

<!---
### Issuer API Integration

To use the AWS SDK for key management in the issuer API, you need to integrate the AWS SDK extension into your project.
The extension provides a more integrated alternative to the platform-agnostic `AWSKeyRestAPI` found in the base walt.id
crypto library.

in the [main function](https://github.com/walt-id/waltid-identity/blob/main/waltid-services/waltid-issuer-api/src/main/kotlin/id/walt/issuer/Main.kt) of the issuer-api, you can initialize the AWS SDK extension as follows:

```kotlin
suspend fun main(args: Array<String>) {
  ServiceMain(
    ServiceConfiguration("issuer"), ServiceInitialization(
      features = FeatureCatalog,
      featureAmendments = mapOf(
        CommonsFeatureCatalog.authenticationServiceFeature to issuerAuthenticationPluginAmendment
      ),
      init = {
        WaltidServices.minimalInit()
        WaltCryptoAws.init() // Initialize the AWS SDK extension
      },
      run = WebService(Application::issuerModule).run()
    )
  ).main(args)
}
```
-->

### Key generation

To create the key you can use the onboard endpoint provided by the issuer API and provide the necessary parameters
to create the key in the AWS KMS service.

#### Creation via Issuer API

**Option: Request**

**Endpoint:**
`/onboard/issuer` | [API Reference](https://issuer.demo.walt.id/swagger/index.html#/Issuer%20onboarding/post_onboard_issuer)

**Example Request**

```bash
curl -X 'POST' \
  'https://issuer.demo.walt.id/onboard/issuer' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": {
    "backend": "aws",
    "keyType": "secp256r1",
    "config": {
      "auth": {
        "region": "eu-central-1",
      },
      "tags": {
        "key": "value"
      }
    }
  },
  "did": {
    "method": "jwk"
  }
}'
```

**Body**

```json
{
  "key": {
    "backend": "aws",
    "keyType": "secp256r1",
    "config": {
      "auth": {
        "region": "eu-central-1",
      },
      "tags": {
        "key": "value"
      }
    }
  },
  "did": {
    "method": "jwk"
  }
}
```

**Body Parameters**

- `key`
    - `backend`: _String_ - Specifies the storage type of key. It can be `jwk` (managed by you), `aws` (managed
      by
      AWS KMS using their kotlin SDK ) and others. Learn more about different
      types [here](https://docs.walt.id/community-stack/issuer/key-management/overview.md).
    - `keyType`: _String_ - the algorithm used to generate the key. Supported AWS KMS values are `secp256r1`, `secp384r1`, `secp521r1`, `secp256k1`, `RSA`, `RSA3072`, and `RSA4096`. `Ed25519` is not supported by AWS KMS signing keys.
    - `config`
        - `auth`
            - `region`: _String_ - The region where the AWS KMS service is located.
        - `tags`: _Object_ - The metadata tags to add to the key for [AWS](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html)
- `did`:
    - `method`: _String_ - Specifies the DID method. It can be key, jwk, web, cheqd.

**Option: Response**

**Example Response**

The onboard/issuer endpoint will return an object containing both the generated key in JWK format and the related DID.

```json
{
  "issuerKey": {
    "type": "aws",
    "config": {
      "auth": {
        "region": "eu-central-1"
      }
    },
    "id": "324ebf67-6bcc-4439-8b81-260bf0a82532",
    "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"RfvJGDXOjz3NOSKgZ0VlijXST8S-j96DrG0C1AMNAK8\",\"y\":\"vSt2q7yIy0-AhAirMuuDmUScxkgf4JVfId-vTETraQA\"}",
    "_keyType": "secp256r1"
  },
  "issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IlJmdkpHRFhPanozTk9TS2daMFZsaWpYU1Q4Uy1qOTZEckcwQzFBTU5BSzgiLCJ5IjoidlN0MnE3eUl5MC1BaEFpck11dURtVVNjeGtnZjRKVmZJZC12VEVUcmFRQSJ9"
}
```

**Properties**

- `type`: _String_ - the type of key can be either "aws" when using AWS KMS or "jwk" when providing the key in
  full as JWK.
- `config`
    - `auth`
        - `region`: _String_ - The region where the AWS KMS service is located.
- `id`: _String_ - the ID of the key in the Transit Engine.
- `_publicKey` (optional): _Array_ - The public key can be fetched by the issuer API or directly provided, saving
  resources and reducing network requests.
- `_keyType` (optional): _String_ - The key type can be fetched by the issuer API or directly provided, saving resources
  and reducing network requests.
- `issuerDid`: _String_ - the DID of the issuer.

### Key Usage

Once you have successfully created a key that is one of the supported types listed above, you can use it in
sign and issue operations offered by the issuer API.

If you've already had a look at
our `/sign`, `/issue`, `/batchIssue`
endpoints, you have seen that they all follow a similar request body structure, where the key that should be
used for signing credentials is provided via the `issuerKey` property. Now instead of providing the key as JWK, we
provide
a reference to a key stored in Vault with the required parameters and access credentials.

Below you can see an example of
`issuerKey` object referencing a key stored in AWS.

**Option: Example IssuerKey Object**

```json 
{
  "issuerKey": {
    "type": "aws",
    "config": {
      "auth": {
        "region": "eu-central-1",
      },
      "tags": {
        "key": "value"
      }
    },
    "id": "324ebf67-6bcc-4439-8b81-260bf0a82532",
    "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"RfvJGDXOjz3NOSKgZ0VlijXST8S-j96DrG0C1AMNAK8\",\"y\":\"vSt2q7yIy0-AhAirMuuDmUScxkgf4JVfId-vTETraQA\"}",
    "_keyType": "secp256r1"
  },
  "issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IlJmdkpHRFhPanozTk9TS2daMFZsaWpYU1Q4Uy1qOTZEckcwQzFBTU5BSzgiLCJ5IjoidlN0MnE3eUl5MC1BaEFpck11dURtVVNjeGtnZjRKVmZJZC12VEVUcmFRQSJ9"
}
```

**Properties**

- `type`: _String_ - the type of key can be either "aws" when using AWS KMS or "jwk" when providing the key in
  full as JWK.
-
- `id`: _String_ - the ID of the key in the Transit Engine.
- `config`
    - `auth`
        - `region`: _String_ - The region where the AWS KMS service is located.
- `_publicKey` (optional): _Array_ - The public key can be fetched by the issuer API or directly provided, saving
  resources and reducing network requests.
- `_keyType` (optional): _String_ - The key type can be fetched by the issuer API or directly provided, saving resources
  and reducing network requests.

**Option: Example Issuance Request**

## Example Issuance Request

Below you can see example issuance request
to [`jwt/issue`](https://issuer.demo.walt.id/swagger/index.html#/Credential%20Issuance/post_openid4vc_jwt_issue) using
a key created in AWS kms to
sign the credential.

[Api Reference](https://issuer.demo.walt.id/swagger/index.html#/Credential%20Issuance/post_openid4vc_jwt_issue)

```bash
curl -X 'POST' \
  'https://issuer.demo.walt.id/openid4vc/jwt/issue' \
  -H 'accept: text/plain' \
  -H 'statusCallbackUri: https://example.com/$id' \
  -H 'Content-Type: application/json' \
  -d '{
  "issuerKey": {
    "type": "aws",
    "config": { 
      "auth": {
        "region": "eu-central-1",
      },
      "tags": {
        "key": "value"
      }
    },
    "id": "324ebf67-6bcc-4439-8b81-260bf0a82532",
    "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"RfvJGDXOjz3NOSKgZ0VlijXST8S-j96DrG0C1AMNAK8\",\"y\":\"vSt2q7yIy0-AhAirMuuDmUScxkgf4JVfId-vTETraQA\"}",
    "_keyType": "secp256r1"
  },
  "issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IlJmdkpHRFhPanozTk9TS2daMFZsaWpYU1Q4Uy1qOTZEckcwQzFBTU5BSzgiLCJ5IjoidlN0MnE3eUl5MC1BaEFpck11dURtVVNjeGtnZjRKVmZJZC12VEVUcmFRQSJ9",
  "credentialData": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://purl.imsglobal.org/spec/ob/v3p0/context.json"
    ],
    "id": "urn:uuid:THIS WILL BE REPLACED WITH DYNAMIC DATA FUNCTION (see below)",
    "type": [
      "VerifiableCredential",
      "OpenBadgeCredential"
    ],
    "name": "JFF x vc-edu PlugFest 3 Interoperability",
    ... 
  },
  "mapping": {
    "id": "<uuid>",
     ... 
  }
}'
```

**Header Parameters**

- `statusCallbackUri`: _URL_ - Receive updates on the created issuance process, e.g. when a credential was successfully
  claimed. The parameter expects a URL which can accept a JSON POST request. The URL can also hold a `$id`, which will
  be
  replaced by the issuance session id. For example: `https://myurl.com/$id`, `https://myurl.com`
  or `https://myurl.com/test/$id`
  <br/>
  <br />
  <details><summary>Expand To Learn More</summary>

  <br /> 

  **Body**

  The data send to the provided URL will contain a JSON body:
    - `id` : _String_ - the issuance session id
    - `type`: _String_ - the event type
    - `data`: _JsonObject_ - the data for the event

  **Event Types**

  Possible events (event types) and their data are:
    - `resolved_credential_offer` with the credential offer as JSON (in our Web Wallet: called when the issuance offer
      is
      entered into the wallet, but not processing / accepted yet)
    - `requested_token` with the issuance request for the token as json object (called for the token required to receive
      the
      credentials)

  Credential issuance (called for every credential that's issued (= requested from wallet))
    - `jwt_issue` with `jwt` being the issued jwt
    - `sdjwt_issue` with `sdjwt` being the issued sdjwt
    - `batch_jwt_issue` with `jwt` being the issued jwt
    - `batch_sdjwt_issue` with `sdjwt` being the issued sdjwt
    - `generated_mdoc` with `mdoc` being the CBOR (HEX) of the signed mdoc

  To allow for secure business logic flows, if a callback URL is set, and it cannot be reached, the issuance will not
  commence further (after that point). If no callback URL is set, the issuance logic does not change in any way.

  </details>

**Body**

As you can see for the property `issuerKey` we only provided the required parameters of the TSE Key Reference Object
described above and left out `_publicKey` and `_keyType`

```json
{
  "issuerKey": {
    "type": "aws",
    "config": {
      "auth": {
        "region": "eu-central-1",
      },
      "tags": {
        "key": "value"
      }
    },
    "id": "324ebf67-6bcc-4439-8b81-260bf0a82532",
    "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"RfvJGDXOjz3NOSKgZ0VlijXST8S-j96DrG0C1AMNAK8\",\"y\":\"vSt2q7yIy0-AhAirMuuDmUScxkgf4JVfId-vTETraQA\"}",
    "_keyType": "secp256r1"
  },
  "issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IlJmdkpHRFhPanozTk9TS2daMFZsaWpYU1Q4Uy1qOTZEckcwQzFBTU5BSzgiLCJ5IjoidlN0MnE3eUl5MC1BaEFpck11dURtVVNjeGtnZjRKVmZJZC12VEVUcmFRQSJ9",
  "credentialData": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://purl.imsglobal.org/spec/ob/v3p0/context.json"
    ],
    "id": "urn:uuid:THIS WILL BE REPLACED WITH DYNAMIC DATA FUNCTION (see below)",
    "type": [
      "VerifiableCredential",
      "OpenBadgeCredential"
    ],
    "name": "JFF x vc-edu PlugFest 3 Interoperability",
    ...
  },
  "mapping": {
    "id": "<uuid>",
    ...
  }
}
```