---
title: "Create a security key"
method: POST
path: "/v3/subscriptions/{subscriptionId}/security_key"
tags: ["subscriptions"]
---

# Create a security key

`POST /v3/subscriptions/{subscriptionId}/security_key`

Create a new security key for your subscription.

When you create a new subscription, a one-time `securityKey` is one of the generated values in the response. All event notifications sent to your `notificationUrl` are signed with this key using the HMAC-SHA256 algorithm. The key is sent as the `x-bill-sha-signature` header value in the notification.

You can use the security key to verify all notifications sent to you. It is good practice to keep the security key for your subscription updated in a timely manner. You can use this endpoint to generate a new security key based on your desired frequency.

See [Webhooks](https://developer.bill.com/docs/webhooks) in the Guides section for more information, sample requests, and notification payloads for BILL events.

## Path parameters

- `subscriptionId` string, required — BILL-generated ID of the subscription

## Headers

- `X-Idempotent-Key` string, required
- `sessionId` string, nullable — API session ID generated with `/v3/login`
- `devKey` string, nullable — Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
- `appKey` string, nullable — Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
- `apiToken` string, nullable — Access token for Spend & Expense API authentication. Set `apiToken` for Spend & Expense webhook events.

## Response `200`

createNewSecurityKey 200 response

- SecurityKeyDto — Security key used for signing outgoing messages.
  - `securityKey` string — BILL-generated security key

---

[API](https://skmtc.net/bill/apis/bill-v3-api.md) · [All operations](https://skmtc.net/bill/apis/bill-v3-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bill/bill-v3-api/versions/0483350c434e/schema)