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

# ES256 Key Pair Setup

> Generate, verify, protect, register, and rotate the ES256 key pair used for machine-to-machine access to the Credit Benchmark API.

You will end up with two files:

* `es256-private.pem`: keep this on the machine that calls our API. Never share it by email, chat, ticket or code repository.
* `es256-public.pem`: send this to us for onboarding.

## Before you start

You need **OpenSSL 3.0 or later**. Check with:

```bash theme={null}
openssl version
```

* **Windows:** install it via winget, Chocolatey or Git for Windows.
* **macOS:** the built-in version may be LibreSSL. Run `brew install openssl` if the output does not show OpenSSL 3 or later.

If your terminal reports that `openssl` is not recognised, install it and open a new terminal window.

> [!NOTE]
>
> Generate the keys on the machine that will call our API, whether a server or a laptop, so the private key never has to be copied elsewhere.

## Step 1: Generate the keys

Run these commands in PowerShell, Command Prompt, bash or zsh. The first creates the private key (EC P-256, PKCS#8 format). The second derives the matching public key.

```bash theme={null}
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve -out es256-private.pem
openssl pkey -in es256-private.pem -pubout -out es256-public.pem
```

## Step 2: Verify the keys

Run these commands before sending anything.

```bash theme={null}
openssl pkey -in es256-private.pem -check -noout
openssl pkey -pubin -in es256-public.pem -text -noout
```

Check that:

* The first command prints `Key is valid`.
* The second shows `ASN1 OID: prime256v1` and `NIST CURVE: P-256`.
* `es256-private.pem` begins with `-----BEGIN PRIVATE KEY-----`.
* `es256-public.pem` begins with `-----BEGIN PUBLIC KEY-----`.

If the private key begins with `BEGIN EC PRIVATE KEY`, convert it to PKCS#8:

```bash theme={null}
openssl pkcs8 -topk8 -nocrypt -in old-key.pem -out es256-private.pem
```

## Step 3: Protect the private key

> [!WARNING]
>
> Anyone holding `es256-private.pem` can request tokens as your organisation. Treat it like a production password.

Restrict access to the account that runs your integration:

```bash Linux or macOS theme={null}
chmod 600 es256-private.pem
```

```powershell Windows PowerShell theme={null}
icacls es256-private.pem /inheritance:r /grant:r "$($env:USERNAME):R"
```

* In production, store it in a secrets manager such as Azure Key Vault, AWS Secrets Manager or HashiCorp Vault.
* Never email it, attach it to a ticket, paste it into chat or commit it to a repository. If you test with Postman, keep it in the Postman Vault or as a current value only.
* If you think it has leaked, tell us immediately.

## Step 4: Send us the public key

Send only `es256-public.pem` to your Credit Benchmark contact. Include:

* Your organisation name
* The environment (Sandbox or Production)
* A technical contact
* The scopes you need
* The key fingerprint

We use the fingerprint to confirm the key was not altered in transit. Calculate it with:

```bash theme={null}
openssl pkey -pubin -in es256-public.pem -outform DER -out es256-public.der
openssl dgst -sha256 es256-public.der
```

Use a separate key pair for each environment. Before you send, check that the attachment is `es256-public.pem` and that no private key file is attached. We may call your technical contact to read back the fingerprint before activating the key.

Once the key is registered, we send your onboarding pack. See [what you receive back](/api-reference/authentication/overview#what-you-receive-back).

## Key rotation

Replace your key pair at least every 12 months, or immediately if the private key may have been exposed.

**1. Generate a new pair**

Repeat Steps 1 and 2 using new file names, such as `es256-private-2027.pem`.

**2. Send the new public key**

Send it as in Step 4, with the subject `M2M API key rotation - [Your organisation name] - [Environment]` and your existing `OAuthClientId`.

**3. Receive a new KID**

We reply with a new `KID`. Your `OAuthClientId` does not change.

**4. Switch over**

Switch your integration to the new private key and `KID`, then tell us. We revoke the old `KID` and you securely delete the old private key.

> [!WARNING]
>
> For a suspected leak, skip the overlap and ask us to revoke the old key straight away.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.