Import a Key

This API is used to import an existing Key into FusionAuth.

For RSA pairs, possible key lengths are: 1024 (only valid when importing a public key for signature verification), 2048, 3072 or 4096.

For EC pairs, possible key lengths are: 256, 384, or 521.

Import an existing Key with a randomly generated Id

POST/api/key/import

OpenAPI Spec

Import an existing Key with the provided unique Id

POST/api/key/import/{keyId}

OpenAPI Spec

Request#

Request Parameters#

keyId UUID optional

The unique Id of the Key. Use if you want to specify a known UUID. This is useful if you are migrating from an existing system or will otherwise depend on having a known key Id.

Request Body#

key.algorithm String optional

The algorithm used to generate the Key. The algorithm will be inferred if it is not passed explicitly. The following values represent algorithms supported by FusionAuth:

Ed25519 - EdDSA using the Ed25519 parameter set Available since 1.62.0
ES256 - ECDSA using P-256 curve and SHA-256 hash algorithm
ES384 - ECDSA using P-384 curve and SHA-384 hash algorithm
ES512 - ECDSA using P-521 curve and SHA-512 hash algorithm
RS256 - RSA using SHA-256 hash algorithm
RS384 - RSA using SHA-384 hash algorithm
RS512 - RSA using SHA-512 hash algorithm
HS256 - HMAC using SHA-256 hash algorithm
HS384 - HMAC using SHA-384 hash algorithm
HS512 - HMAC using SHA-512 hash algorithm
None - Secret Available since 1.64.0

key.certificate String optional

The certificate to import. The publicKey will be extracted from the certificate.

key.kid String optional

The Key identifier 'kid'. When this value is omitted, one will be generated. For Secrets, the kid is derived from key.name and cannot be specified separately.

key.name String required

The name of the Key. It must be unique among all Keys. For Secrets, this value is used to derive the kid.

key.publicKey String optional

The Key public key. If the key is only to be used for signing, only a private key is necessary and this field may be omitted. This field should be omitted when importing an HMAC key type.

key.privateKey String optional

The Key private key. If the key is only to be used for signature validation, only a public key is necessary and this field may be omitted. This field should be omitted when importing an HMAC key type.

key.secret String optional

The Key secret. This field is required if importing an HMAC key type or a Secret. Secrets must be 256 characters or less.

key.type String optional

The Key type. This field is required if importing an HMAC key type, or if importing a public key / private key pair. The possible values are:

EC
OKP Available since 1.62.0
RSA
HMAC
Secret Available since 1.64.0

Example Request JSON

{
  "key": {
    "name": "SHA-256 with RSA",
    "kid": "zamAX0036820RULfdjUV6YkhYbY",
    "certificate": "MIICrjCCAZagAwIBAQIQeA4dW+47Q7KuyNuZuZrcTjANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDEwhhY21lLmNvbTAeFw0xOTA3MDMyMTI0MzJaFw0yOTA3MDMyMTI0MzJaMBMxETAPBgNVBAMTCGFjbWUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnbNGwtU33S4vbipGeIwe/DhLEfc5FaEOHK4WeQ3QF8zZGyI09bNQdkp8uNTFfVehIgmvYHmJWPeaNrYK//qjWAsSvYYoytj1j4BywI8uLSjt8QvzaoFUMOi1cBbXM2586R7yTRm7jMk91MLM101zkrf1cmFdRUwTpeJjw66XG3JlTGZCmZsJG7m6+nbe5LHt4CiufmJHujGeFzgwby3jXZtuK1y3ua3380Fv95JyG3TucnMwEw5EYQ8Q+dZzNC8OSaKrgmnN0gWdsJ7P7vu6lMy6sXKhvcxo1p+tXywYPFJahxA+rZDG16RLbUppCx10q8tIcFKeAyl4eywzBaBLxwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBbsHWIBDwW1hFEin0D5BK/rwpCIZ4jlJ9PON4q0rF/tl9+pSzTqMeEqU0NMlJ7Xm2O5U0i8Sy8Lhemo9qYCZ76qEiHFZwQBmNAC4de92KMcw4Q7q5CVjTGv3X+Avlg/c+I+zJLO/IJlzhOvHj+iCeBZDznt6/KlFfXA9EvlznxqZCQHSf2f94UlvBmqbVYOfXE5+OQ3URyNyh88g9yClSb4hzu1lmzevZ/AVbe2kTjZQQWB0TmqPg/6SS+nhsauAMK1kSlSK9t6CPz/L7olJeAi7G/PZPaYG1gIFVFaBnYM0rwagQGtPMi1uCERCKrkUlBh6gSyN7SGJBvWEh6+zZF"
  }
}

Response#

The response for this API contains the Key that was imported.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

key.algorithm String

The algorithm used to generate the key. For Secrets, this value will be None.

key.certificate String

The X.509 certificate. This field is omitted for HMAC keys and Secrets.

key.certificateInformation Map<String, Object>

The RSA or EC certificate information. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.issuer String

The issuer of the certificate. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.md5Fingerprint String

The md5 fingerprint of the certificate. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.serialNumber String

The serial number of the certificate. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.sha1Fingerprint String

The SHA-1 fingerprint of the certificate. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.sha1Thumbprint String

The SHA-1 thumbprint of the certificate. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.sha256Fingerprint String

The SHA-256 fingerprint of the certificate. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.sha256Thumbprint String

The SHA-256 thumbprint of the certificate. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.subject String

The subject of the certificate. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.validFrom Integer

The UNIX time in milliseconds marking the start of the certificate validity period. This field is omitted for HMAC keys and Secrets.

key.certificateInformation.validTo Integer

The UNIX time in milliseconds marking the expiration certificate. This field is omitted for HMAC keys and Secrets.

key.expirationInstant Integer

The instant marking the expiration certificate. This field is omitted for HMAC keys and Secrets.

key.hasPrivateKey Boolean

Because the private key will never be returned in the API response, this value will indicate if the private key is stored in FusionAuth. This field is omitted for HMAC keys and Secrets.

key.id UUID

The Id of the Key.

key.insertInstant Long

The instant that the key was added to the FusionAuth database.

key.issuer String

The issuer of the certificate. This field is omitted for HMAC keys and Secrets.

key.kid String

The key identifier 'kid'.

key.lastUpdateInstant Long

The instant that the key was updated in the FusionAuth database.

key.length String

The length of the certificate. This field is omitted for HMAC keys and Secrets.

key.name String

The name of the key.

key.publicKey String

The certificate public key. This field is omitted for HMAC keys and Secrets.

key.type String

The key type. The possible values are:

EC
OKP Available since 1.62.0
RSA
HMAC
Secret Available since 1.64.0

Example HMAC Key Response JSON

{
  "key": {
    "algorithm": "HS256",
    "id": "092dbedc-30af-4149-9c61-b578f2c72f59",
    "insertInstant": 1562171137000,
    "kid": "10d51735a5",
    "lastUpdateInstant": 1595361143101,
    "name": "OpenID Connect compliant HMAC using SHA-256",
    "type": "HMAC"
  }
}

Example RSA Key Response JSON

{
  "key": {
    "algorithm": "RS256",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIICrjCCAZagAwIBAQIQeA4dW+47Q7KuyNuZuZrcTjANBgkqhkiG9w0BAQsFADAT\nMREwDwYDVQQDEwhhY21lLmNvbTAeFw0xOTA3MDMyMTI0MzJaFw0yOTA3MDMyMTI0\nMzJaMBMxETAPBgNVBAMTCGFjbWUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A\nMIIBCgKCAQEAnbNGwtU33S4vbipGeIwe/DhLEfc5FaEOHK4WeQ3QF8zZGyI09bNQ\ndkp8uNTFfVehIgmvYHmJWPeaNrYK//qjWAsSvYYoytj1j4BywI8uLSjt8QvzaoFU\nMOi1cBbXM2586R7yTRm7jMk91MLM101zkrf1cmFdRUwTpeJjw66XG3JlTGZCmZsJ\nG7m6+nbe5LHt4CiufmJHujGeFzgwby3jXZtuK1y3ua3380Fv95JyG3TucnMwEw5E\nYQ8Q+dZzNC8OSaKrgmnN0gWdsJ7P7vu6lMy6sXKhvcxo1p+tXywYPFJahxA+rZDG\n16RLbUppCx10q8tIcFKeAyl4eywzBaBLxwIDAQABMA0GCSqGSIb3DQEBCwUAA4IB\nAQBbsHWIBDwW1hFEin0D5BK/rwpCIZ4jlJ9PON4q0rF/tl9+pSzTqMeEqU0NMlJ7\nXm2O5U0i8Sy8Lhemo9qYCZ76qEiHFZwQBmNAC4de92KMcw4Q7q5CVjTGv3X+Avlg\n/c+I+zJLO/IJlzhOvHj+iCeBZDznt6/KlFfXA9EvlznxqZCQHSf2f94UlvBmqbVY\nOfXE5+OQ3URyNyh88g9yClSb4hzu1lmzevZ/AVbe2kTjZQQWB0TmqPg/6SS+nhsa\nuAMK1kSlSK9t6CPz/L7olJeAi7G/PZPaYG1gIFVFaBnYM0rwagQGtPMi1uCERCKr\nkUlBh6gSyN7SGJBvWEh6+zZF\n-----END CERTIFICATE-----",
    "certificateInformation": {
      "issuer": "CN=acme.com",
      "md5Fingerprint": "FC:36:CD:0B:9C:B7:62:F0:A9:16:AE:72:8E:F8:7D:D8",
      "serialNumber": "78:0E:1D:5B:EE:3B:43:B2:AE:C8:DB:99:B9:9A:DC:4E",
      "sha1Fingerprint": "CD:A9:80:5F:4D:37:EB:CD:B4:45:42:DF:76:35:15:E9:89:21:61:B6",
      "sha1Thumbprint": "zamAX0036820RULfdjUV6YkhYbY",
      "sha256Fingerprint": "33:7C:CB:4C:23:3B:F5:22:49:2F:68:C5:FA:D1:6E:3C:72:54:CB:3C:E6:D1:70:08:55:FC:43:24:9A:98:05:CF",
      "sha256Thumbprint": "M3zLTCM79SJJL2jF-tFuPHJUyzzm0XAIVfxDJJqYBc8",
      "subject": "CN=acme.com",
      "validFrom": 1562189072183,
      "validTo": 1877808272183
    },
    "expirationInstant": 1877808272183,
    "hasPrivateKey": false,
    "id": "780e1d5b-ee3b-43b2-aec8-db99b99adc4e",
    "insertInstant": 1562189072183,
    "issuer": "acme.com",
    "kid": "zamAX0036820RULfdjUV6YkhYbY",
    "lastUpdateInstant": 1595361143101,
    "length": 2048,
    "name": "SHA-256 with RSA",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnbNGwtU33S4vbipGeIwe\n/DhLEfc5FaEOHK4WeQ3QF8zZGyI09bNQdkp8uNTFfVehIgmvYHmJWPeaNrYK//qj\nWAsSvYYoytj1j4BywI8uLSjt8QvzaoFUMOi1cBbXM2586R7yTRm7jMk91MLM101z\nkrf1cmFdRUwTpeJjw66XG3JlTGZCmZsJG7m6+nbe5LHt4CiufmJHujGeFzgwby3j\nXZtuK1y3ua3380Fv95JyG3TucnMwEw5EYQ8Q+dZzNC8OSaKrgmnN0gWdsJ7P7vu6\nlMy6sXKhvcxo1p+tXywYPFJahxA+rZDG16RLbUppCx10q8tIcFKeAyl4eywzBaBL\nxwIDAQAB\n-----END PUBLIC KEY-----",
    "type": "RSA"
  }
}

Example EC Key Response JSON

{
  "key": {
    "algorithm": "ES256",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIBJzCBy6ADAgEBAhEAwUtQ5YaLTb6fPAKM0FFbETAMBggqhkjOPQQDAgUAMBMx\nETAPBgNVBAMTCGFjbWUuY29tMB4XDTIxMTAwMjEzNDE1MVoXDTMxMTAwMjEzNDE1\nMVowEzERMA8GA1UEAxMIYWNtZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNC\nAARPysdu/AKSICtkZa9hlBGb7vJHJ0GHWYXEeyTYDCPd2XoT5icVAZQ5GVU1q2WV\nEaVJRmlFuGqWElvYLIRYrce2MAwGCCqGSM49BAMCBQADSQAwRgIhAJCXC5Ys25Wk\nYXeC1bWjyt71p8Yn1B//DZo+SzQrBVF+AiEA3u6an0m+wsO1dnNN1wtXdUsa5Avo\nOjME4ZLJHhtGQ1I=\n-----END CERTIFICATE-----",
    "certificateInformation": {
      "issuer": "CN=acme.com",
      "md5Fingerprint": "E5:50:70:3A:88:56:7C:BE:CB:FA:50:29:19:B5:CE:2D",
      "serialNumber": "00:C1:4B:50:E5:86:8B:4D:BE:9F:3C:02:8C:D0:51:5B:11",
      "sha1Fingerprint": "2F:22:15:AC:7C:2A:67:E8:F3:AB:87:97:3A:E0:84:58:79:A3:35:7F",
      "sha1Thumbprint": "LyIVrHwqZ-jzq4eXOuCEWHmjNX8",
      "sha256Fingerprint": "D5:B0:B5:5E:07:1D:2B:84:A8:7C:5F:89:B7:74:62:2F:8C:57:A8:66:A1:D5:A2:F1:A9:94:70:8F:D3:0D:64:0F",
      "sha256Thumbprint": "1bC1XgcdK4SofF-Jt3RiL4xXqGah1aLxqZRwj9MNZA8",
      "subject": "CN=acme.com",
      "validFrom": 1633182111000,
      "validTo": 1948714911000
    },
    "expirationInstant": 1948714911000,
    "hasPrivateKey": true,
    "id": "c14b50e5-868b-4dbe-9f3c-028cd0515b11",
    "insertInstant": 1633182111648,
    "issuer": "acme.com",
    "kid": "LyIVrHwqZ-jzq4eXOuCEWHmjNX8",
    "lastUpdateInstant": 1633182111648,
    "length": 256,
    "name": "ECDSA using P-256 curve and SHA-256",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAET8rHbvwCkiArZGWvYZQRm+7yRydB\nh1mFxHsk2Awj3dl6E+YnFQGUORlVNatllRGlSUZpRbhqlhJb2CyEWK3Htg==\n-----END PUBLIC KEY-----",
    "type": "EC"
  }
}

Example EdDSA Key Response JSON

{
  "key": {
    "algorithm": "Ed25519",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIHsMIGfoAMCAQECEQDqdRGGNnhIwI8IEfDjwZN7MAUGAytlcDAYMRYwFAYDVQQD\nEw1mdXNpb25hdXRoLmlvMB4XDTI1MTIxODE2MDUyNVoXDTM1MTIxODE2MDUyNVow\nGDEWMBQGA1UEAxMNZnVzaW9uYXV0aC5pbzAqMAUGAytlcAMhAI+wTC3wU30tqiGR\n8RsFrAYl++dNZTRIdwUqPmMv3xeqMAUGAytlcANBANiOCGE+XoUorYo13gor1PWM\n6sL7j2oDBbSExzThihvYXyO7Lx7s8ZCgJ8rIcxgDQRJbhq1n5oxMAvGnzezDMwQ=\n-----END CERTIFICATE-----",
    "certificateInformation": {
      "issuer": "CN=fusionauth.io",
      "md5Fingerprint": "74:19:09:95:D9:6F:52:D9:83:D5:CD:48:D2:26:34:A2",
      "serialNumber": "00:EA:75:11:86:36:78:48:C0:8F:08:11:F0:E3:C1:93:7B",
      "sha1Fingerprint": "AB:6D:71:A6:B6:36:BA:D3:00:7D:1D:E8:CB:08:25:6F:46:13:EF:51",
      "sha1Thumbprint": "q21xprY2utMAfR3oywglb0YT71E",
      "sha256Fingerprint": "1A:BE:72:43:9A:B6:06:D5:08:32:06:28:A8:1B:DF:73:A2:99:5E:82:FF:C4:A3:FD:F3:9B:5F:5F:80:4A:27:D4",
      "sha256Thumbprint": "Gr5yQ5q2BtUIMgYoqBvfc6KZXoL_xKP985tfX4BKJ9Q",
      "subject": "CN=fusionauth.io",
      "validFrom": 1766073925573,
      "validTo": 2081606725573
    },
    "expirationInstant": 2081606725573,
    "hasPrivateKey": true,
    "id": "ea751186-3678-48c0-8f08-11f0e3c1937b",
    "insertInstant": 1766073925573,
    "issuer": "fusionauth.io",
    "kid": "q21xprY2utMAfR3oywglb0YT71E",
    "lastUpdateInstant": 1766073925573,
    "length": 32,
    "name": "EdDSA using the Ed25519 parameter set",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAj7BMLfBTfS2qIZHxGwWsBiX7501lNEh3BSo+Yy/fF6o=\n-----END PUBLIC KEY-----",
    "type": "OKP"
  }
}