---
title: Customer Credential Signing API Definition
description: If you choose to sign your credentials with your private key, you must implement an API that conforms to this design. You must Update Credential Issuer Profile and provide the URL of your API in credentialSigning.url.
component: pingone-api
page_id: pingone-api:credentials:credential-signing-keys/customer-credential-signing-api-definition
canonical_url: https://developer.pingidentity.com/pingone-api/credentials/credential-signing-keys/customer-credential-signing-api-definition.html
section_ids:
  customer-credential-signing-request-data-model: Customer credential signing request data model
  customer-credential-signing-response-data-model: Customer credential signing response data model
---

# Customer Credential Signing API Definition

If you choose to sign your credentials with your private key, you must implement an API that conforms to this design. You must [Update Credential Issuer Profile](../credential-profiles/update-credential-issuer-profile.html) and provide the URL of your API in `credentialSigning.url`.

The request for signing contains an array of payloads that you must sign. Each payload has a key ID and a corresponding credential signing key ID. The key ID, `kid`, you define in the public signing key submitted in the request to [Create Customer Signing Public Key](create-customer-signing-public-key.html). The credential signing key ID, `credentialSigningKeyId`, the PingOne service assigns in the response to [Create Customer Signing Public Key](create-customer-signing-public-key.html).

## Customer credential signing request data model

| Property                          | Type      | Required? | Mutable?  | Description                                                                                                                                                                                                               |
| --------------------------------- | --------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `purpose`                         | String    | Optional  | Immutable | A free-format string for auditing.                                                                                                                                                                                        |
| `payloads`                        | Object\[] | Required  | Immutable | Array of payload objects that you must sign.                                                                                                                                                                              |
| `payloads.payload`                | String    | Required  | Immutable | Opaque data to be individually signed by your service using your private key.                                                                                                                                             |
| `payloads.kid`                    | String    | Required  | Immutable | The key ID in the public credential signing key JWK, submitted to the credential signing service, to use to sign the payload.                                                                                             |
| `payloads.credentialSigningKeyId` | String    | Required  | Immutable | Unique identifier (UUID) of the credential signing key to use to sign the payload. PingOne credentialing service generates this UUID for each public credential signing key you submit to the credential signing service. |

In `payloads.payload`, the service supplies the base64-encoded JWT header, derived from the public key the service expects you to use, and the base64-encoded payload, the opaque credential object to sign, separated by a literal period.

You can use either `payloads.kid` or `payloads.credentialSigningKeyId` to find the correct private key for signing.

## Customer credential signing response data model

| Property             | Type      | Required? | Mutable?  | Description                                                                           |
| -------------------- | --------- | --------- | --------- | ------------------------------------------------------------------------------------- |
| `signedData`         | Object\[] | Required  | Immutable | Array of signed payload objects.                                                      |
| `payloads.payload`   | String    | Required  | Immutable | The `payload` sent in the request.                                                    |
| `payloads.signature` | String    | Required  | Immutable | The base64-encoded signature you generated using your private credential signing key. |

Learn more about Java Web Tokens (JWT) in [Introduction to JSON Web Tokens (JWT)](https://docs.pingidentity.com/developer-resources/dev_jwt_jose_overview.html).