Create a new Issuer.

loading...

POST

/control/issuer

Send

Header

Body

An endpoint used to create a new Issuer in the Issuer Service.

If statusBits is provided within the request, the Issuer will keep a Status List, where each status will use the statusBits amount of bits. Each issued credential could then have one of 2 ^ statusBits possible statuses. Usually, status 0 is reserved as VALID, status 1 as INVALID, and status 2 as SUSPENDED.

Signing key

The signing key used by the Issuer to sign verifiable credentials may either be generated and managed by Issuer Service, or provided through a 3rd-party KMS through the issuerKeyConfig optional parameter.

3rd-party KMS integration

The caller may provide a Key Management System credentials config for the key pair which will represent the cryptographic identity of a newly-created issuer, and subsequently sign the issued credentials.

Currently we support integration with HashiCorp Vault Transit secrets engine and Google Cloud KMS.

Currently we only support signatures created with ECDSA using P-256 curve with SHA-256 hash function - ES256.

Issuing certain kinds of VCs requires including a X.509 certificate chain for the Issuer's signing key. When using a KMS backend for signing, the caller MUST provide the certificate chain for the chosen signing key through the certChain parameter.

HashiCorp Vault Transit secrets engine

HashiCorp Vault Transit Engine access credentials format:

• vaultAddr - HTTPS URL of the HashiCorp Vault Transit Engine service
• tlsTrustAnchorCert - TLS certificate for HashiCorp Vault Transit Engine. This certificate should be root CA certificate (issuer == subject). Intermediary CA certificates are not supported.
• keyName - Name of the key which will be used to sign issued credentials. Key name can contain only alphanumeric and '-', '_', '.' characters.
• keyVersion - version of the key which will be used to sign issued credentials
• vaultToken - access token for a policy with following paths and capabilities:
  • transit/sign/{key-name} with update capability
  • transit/export/public-key/{key-name}/* with read capability

In case vault token is expired, one should use update credentials endpoint to set a new token.

Google Cloud KMS

Google Cloud KMS access credentials format:

• projectId - Google Cloud project ID where key is stored
• location - Google Cloud key ring location
• keyRingName - key ring name where key is stored
• keyName - key name

The role roles/cloudkms.signerVerifier should be given to our Issuer Service Service Account.

Issuer ID

The caller may provide a custom issuerId which must be unique across all issuers registered to the Issuer Service. This value will be used as a unique identifier to the newly registered issuer, and will also be embedded in the credential issuer identifier URL within the Credential Issuer Metadata, and other appropriate .well-known endpoints (e.g. OAuth Authorization Server, etc.). If omitted, the issuerId will be generated by the Issuer Service in the form of an UUID according to the RFC 4122.

Issuer Metadata

The caller may also provide certain Credential Issuer Metadata properties that will be served on a well-known endpoint once the issuer is created.

More precisely, the following properties may be specified:

• issuerMetadata object containing:
  • display — Array of objects, where each object contains display properties of a Credential Issuer for a certain language according to the specification

Specifying these metadata properties is optional. If they are omitted, only protocol-required parts of Credential Issuer Metadata will be served.

Header Parameters

Response Body

curl -X POST "https://eis.fortid.com/control/issuer" \  -H "X-API-KEY: HCLN4ZKnWYJAfyNkDnQ57gEAHuejD6MN" \  -H "Content-Type: application/json" \  -d '{}'

{
  "issuerId": "university-issuer",
  "issuerPublicKey": "-----BEGIN PUBLIC KEY-----\nMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE1MtHIxlGP5TARqBccrddNm1FnYH1Fp+o\nnETz5KbXPSeG5FGwKMUXGfAmSZJq2gENULFewwymt+9bTXkjBZhh8A==\n-----END PUBLIC KEY-----",
  "issuerMetadataEndpoint": "https://eis.fortid.com/protocol/oid4vci/issuer/university-issuer/.well-known/openid-credential-issuer"
}

{
  "message": "locale not compliant with tags for identifying languages as defined in RFC 5646"
}