> For the complete documentation index, see [llms.txt](https://help.security.gallagher.com/knowledge-hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.security.gallagher.com/knowledge-hub/developer/rest-api/piv-cards.md).
# PIV cards
This tag is a supplement to the main cardholder API documentation ('cardholder' is the Command Centre term for a user). That section describes how to add a card to an existing cardholder in a PATCH, and how to create a cardholder with cards in a POST, but in the interests of brevity its examples do not cover PIV.
The schema / models section gives you the details of the PIV part of a Command Centre card, with examples of what you would submit to create or update one, and what Command Centre will send you when you view one.
The Paths section takes those schema examples and wraps them into a PATCH and a POST. The two differ only in how they wrap the card into the submission body.
If your application will be assigning PIV cards to cardholders, however, the first thing it needs to do is learn the value of some constants for your particular installation of Command Centre.
#### Finding the PIV card type
When you assign any card to a cardholder, PIV or otherwise, you need to provide the identifier of the card type. It will vary between Command Centre installations, so you cannot use a value from another installation or these examples. It will not change while Command Centre is running but it may change at upgrade, so your application should follow this process at startup.
It takes two queries and a loop:
1. `GET /api`.
2. If running 8.00 or earlier, follow the link at `features.cardTypes.cardTypes.href` (which will be to `/api/card_types`), or
3. if running 8.10 or later, follow the link at `features.cardTypes.assign.href` (which will probably be to `/api/card_types/assign`. Both URLs will work in 8.10, but the advantage of this URL is that your operator can access it at a lower privilege level).
4. Iterate through the array to find the element with `credentialClass: piv`, and
5. note its `href`.
You can accomplish the last two steps with the JSONPath filter
`$.results[?(@.credentialClass=='piv')].href`.
Explanation: Command Centre ships with a handful of card types, and administrators can add more, but the one that Command Centre uses for PIV and PIV-I cards has its own credential class. It will look like the example in the GET.
#### Finding the URL to create cardholders
`GET /api`. The link is at `features.cardholders.cardholders.href`.
#### Finding the URL of a cardholder
See the main cardholder documentation, particularly the section on searching cardholders.
#### Licensing
All of the API calls described here require the RESTCardholders licence. If your site is also licensed to use PIV cards, you can access those cards via REST.
## Create a cardholder with a PIV card
> This shows how to create a cardholder with a PIV card.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"PIV cards","description":"This tag is a supplement to the main cardholder API documentation ('cardholder' is the Command\nCentre term for a user). That section describes how to add a card to an existing cardholder in\na [PATCH](cardholders#patch-api-cardholders-id-), and how to create a\ncardholder with cards in a [POST](cardholders#post-api-cardholders), but in the\ninterests of brevity its examples do not cover PIV.\n\nThe schema / models section gives you the details of the PIV part of a Command Centre card, with\nexamples of what you would submit to [create](models#newpivcard) or update one, and what\nCommand Centre will send you when you view one.\n\nThe Paths section takes those schema examples and wraps them into a\n[PATCH](cardholders#patch-api-cardholders-id-) and a\n[POST](cardholders#post-api-cardholders). The two differ only in how they wrap the card\ninto the submission body.\n\nIf your application will be assigning PIV cards to cardholders, however, the first thing it\nneeds to do is learn the value of some constants for your particular installation of Command\nCentre.\n\n### Finding the PIV card type\n\nWhen you assign any card to a cardholder, PIV or otherwise, you need to provide the identifier\nof the card type. It will vary between Command Centre installations, so you cannot use a value\nfrom another installation or these examples. It will not change while Command Centre is running\nbut it may change at upgrade, so your application should follow this process at startup.\n\nIt takes two queries and a loop:\n\n 1. `GET /api`.\n 2. If running 8.00 or earlier, follow the link at `features.cardTypes.cardTypes.href` (which\n will be to `/api/card_types`), or\n 2. if running 8.10 or later, follow the link at `features.cardTypes.assign.href` (which will\n probably be to `/api/card_types/assign`. Both URLs will work in 8.10, but the advantage of\n this URL is that your operator can access it at a lower privilege level).\n 3. Iterate through the array to find the element with `credentialClass: piv`, and\n 4. note its `href`.\n\nYou can accomplish the last two steps with the JSONPath filter\n\n`$.results[?(@.credentialClass=='piv')].href`.\n\nExplanation: Command Centre ships with a handful of card types, and administrators can add\nmore, but the one that Command Centre uses for PIV and PIV-I cards has its own credential class.\nIt will look like the example in the [GET](piv-cards#get-api-cardholders-card-type).\n\n### Finding the URL to create cardholders\n\n`GET /api`. The link is at `features.cardholders.cardholders.href`.\n\n### Finding the URL of a cardholder\n\nSee the main cardholder documentation, particularly the section on [searching\ncardholders](cardholders#get-api-cardholders).\n\n### Licensing\n\nAll of the API calls described here require the RESTCardholders licence. If your site is also\nlicensed to use PIV cards, you can access those cards via REST.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"schemas":{"NewPIVCard":{"title":"New PIV Card","description":"A new PIV card. You would put this in the `cards` array of a cardholder you were creating with a POST,\nor the `cards.add` array of a cardholder you were modifying with a PATCH.\n","type":"object","required":["type","number","pivData"],"properties":{"type":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"The href of the server's PIV card type. This documentation has a section called\n\"finding the PIV card type\" if you need it.\n"}}},"status":{"type":"object","properties":{"value":{"type":"string"}}},"number":{"type":"string","description":"While the card number rules on a PIV or PIV-I card type are different from those on other\ntypes, card numbers are still strings, and the API will accept them from you and return\nthem to you in the same way.\n\nPIV card numbers are the FASC-N with hyphens splitting the major components.\n\nPIV-I card numbers are the CHUID's GUID in decimal.\n"},"pivData":{"type":"object","description":"These are the PIV-specific fields that you can set on a new card. They\nare the same as you [receive from the API](piv-cards#get-api-cardholders-id-%20-PIV-) for\nan existing PIV card except that you do not send a `lastCheckTime`.\n","required":["chuid","contentSigningCert","pivAuthenticationCert"],"properties":{"chuid":{"description":"Required when creating a card, ignored when updating one.\n\nThe FASC-N in the `chuid` block, and its relationship with the card number, is the only\ndifference between PIV and PIV-I cards in Command Centre.\n","$ref":"#/components/schemas/CHUID"},"pivStatus":{"type":"object","description":"The PIV status held in the `type` field in this block is distinct from the generic card\nstatus, which is a different field outside the `pivData` block.\n\nIt is optional. If you omit it when creating a card, the card will be enabled with a status\nof \"NotChecked\", which—despite how it sounds—is a perfectly valid operating status. If\nCommand Centre is doing periodic certificate validation, the status will eventually change\n(to 'normal', all going well).\n\nYou should send this block when creating a card only if you are doing your own certificate\nvalidation.\n\nWhen updating an existing card, this is the only field it makes sense to send (specifically,\nthe `type` field inside it).\n\n`type` must be set to one of these values, based on the result of your validation:\n\n - Normal\n - Offline\n - Revoked\n - Expired\n - CertInChainRevoked\n - CertInChainExpired\n - IssuerSigCertRevoked\n - IssuerSigCertExpired\n - NotTrusted\n - PolicyError\n - OtherError\n - NotChecked\n\nIf you set it to any value except 'NotChecked', 'Normal', or 'Offline', Command Centre will consider the\ncard invalid and deactivate it regardless of what you pass as the card status. You, or\nCommand Centre's periodic certificate validation, may validate the card again later.\n","properties":{"type":{"type":"string","enum":["Normal","Offline","Revoked","Expired","CertInChainRevoked","CertInChainExpired","IssuerSigCertRevoked","IssuerSigCertExpired","NotTrusted","PolicyError","OtherError","NotChecked"]}}},"contentSigningCert":{"type":"string","description":"This is required when creating a PIV or PIV-I card. The API will reject your request if this is\nmissing or not a Base64-encoded certificate, but it will not validate the certificate itself.\n\nThis example is shortened to fit on screen. Real certificates are at least a thousand\ncharacters.\n"},"cardAuthenticationCert":{"type":"string","description":"This contains the CAK, which is necessary for the secure use of contactless cards. It is\nnot required for contact cards.\n\nOptional when creating a PIV or PIV-I card. The API will reject your request if this is\npresent and not a Base64-encoded certificate, but it will not validate the certificate itself.\n"},"pivAuthenticationCert":{"type":"string","description":"This is required when creating a PIV or PIV-I card. The API will reject your request if this is\nmissing or not a Base64-encoded certificate, but it will not validate the certificate itself.\n"},"fingerprints":{"type":"string","description":"If you send this when creating a card, it should be the cardholder's fingerprints contained in\nthe card's Cardholder Fingerprints data object with the error detection code removed: the\nwhole CBEFF structure including the CBEFF_HEADER, CBEFF_BIOMETRIC_RECORD, and\nCBEFF_SIGNATURE_BLOCK components. Refer to Section 9 of NIST Special Publication 800-76-2:\nBiometric Data Specification for Personal Identity Verification.\n\nIt is optional. The API will check that this is Base64, but will not verify that it is\nvalid biometric data.\n"}}}}},"CHUID":{"description":"This is the model of a CHUID block for a PIV card. The only difference between this and a\nPIV-I card is the FASC-N.\n","type":"object","required":["hash","fascn"],"properties":{"hash":{"type":"string","description":"This is the hash of the CHUID object, Base64-encoded. For a 256-bit hash it\nshould be 44 characters long including one `=` pad. The API will reject a string that is\nnot valid Base64, but it will not verify the hash.\n\nRequired when creating a PIV card in versions up to 8.60. Optional in 8.70 and later.\n"},"fascn":{"type":"string","description":"This is the FASC-N identifier. You must supply it when creating a card.\n\nIt must be the same as the card number on a PIV (not PIV-I) card.\n\nOn a PIV-I card, it must not be the same as the card number (and for Federal PIV-I cards\nit will likely begin with fourteen nines).\n"},"orgIdentifier":{"type":"string","description":"Optional."},"duns":{"type":"string","description":"Optional."}}}}},"paths":{"/api/cardholders [PIV]":{"post":{"tags":["PIV cards"],"summary":"Create a cardholder with a PIV card","description":"This shows how to create a cardholder with a PIV card.\n","requestBody":{"description":"When creating a cardholder there are many fields you can send that are not shown here, but\nsince this is the PIV section of the documentation it only shows how to give the new\nperson a PIV card.\n","content":{"application/json":{"schema":{"type":"object","required":["division"],"properties":{"firstName":{"type":"string","description":"You must set either a first or last name when creating a cardholder.\n"},"division":{"type":"object","description":"You must set a division when creating a cardholder.\n","properties":{"href":{"type":"string","format":"uri-reference"}}},"cards":{"description":"An array of cards to give to the new cardholder.\n","type":"array","items":{"$ref":"#/components/schemas/NewPIVCard"}}}}}},"required":true},"responses":{"201":{"description":"Success.\n","headers":{"location":{"description":"The href of the new cardholder.","schema":{"type":"string","format":"uri-reference"}}}},"400":{"description":"The body of the POST did not describe a valid cardholder.\n"}}}}}}
```
## Get details of a PIV cardholder
> You will receive this URL from other calls to the API, in a search result or an access group\
> membership list, for example. The URL is the unique identifier of a cardholder, and calling\
> it returns much of what Command Centre holds for that person, including assigned cards.\
> \
> The result includes an array called \`cards\`. Each element of that array is a credential of\
> some type. If it is a PIV card, it will look like the example here.\
> \
> Note that this example is an array of one.\
> \
> Only the PIV card schema is shown below. The \[main\
> documentation]\(cardholders#get-api-cardholders-id-) covers all the other\
> fields Command Centre holds for a cardholder.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"PIV cards","description":"This tag is a supplement to the main cardholder API documentation ('cardholder' is the Command\nCentre term for a user). That section describes how to add a card to an existing cardholder in\na [PATCH](cardholders#patch-api-cardholders-id-), and how to create a\ncardholder with cards in a [POST](cardholders#post-api-cardholders), but in the\ninterests of brevity its examples do not cover PIV.\n\nThe schema / models section gives you the details of the PIV part of a Command Centre card, with\nexamples of what you would submit to [create](models#newpivcard) or update one, and what\nCommand Centre will send you when you view one.\n\nThe Paths section takes those schema examples and wraps them into a\n[PATCH](cardholders#patch-api-cardholders-id-) and a\n[POST](cardholders#post-api-cardholders). The two differ only in how they wrap the card\ninto the submission body.\n\nIf your application will be assigning PIV cards to cardholders, however, the first thing it\nneeds to do is learn the value of some constants for your particular installation of Command\nCentre.\n\n### Finding the PIV card type\n\nWhen you assign any card to a cardholder, PIV or otherwise, you need to provide the identifier\nof the card type. It will vary between Command Centre installations, so you cannot use a value\nfrom another installation or these examples. It will not change while Command Centre is running\nbut it may change at upgrade, so your application should follow this process at startup.\n\nIt takes two queries and a loop:\n\n 1. `GET /api`.\n 2. If running 8.00 or earlier, follow the link at `features.cardTypes.cardTypes.href` (which\n will be to `/api/card_types`), or\n 2. if running 8.10 or later, follow the link at `features.cardTypes.assign.href` (which will\n probably be to `/api/card_types/assign`. Both URLs will work in 8.10, but the advantage of\n this URL is that your operator can access it at a lower privilege level).\n 3. Iterate through the array to find the element with `credentialClass: piv`, and\n 4. note its `href`.\n\nYou can accomplish the last two steps with the JSONPath filter\n\n`$.results[?(@.credentialClass=='piv')].href`.\n\nExplanation: Command Centre ships with a handful of card types, and administrators can add\nmore, but the one that Command Centre uses for PIV and PIV-I cards has its own credential class.\nIt will look like the example in the [GET](piv-cards#get-api-cardholders-card-type).\n\n### Finding the URL to create cardholders\n\n`GET /api`. The link is at `features.cardholders.cardholders.href`.\n\n### Finding the URL of a cardholder\n\nSee the main cardholder documentation, particularly the section on [searching\ncardholders](cardholders#get-api-cardholders).\n\n### Licensing\n\nAll of the API calls described here require the RESTCardholders licence. If your site is also\nlicensed to use PIV cards, you can access those cards via REST.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An internal identifier."}},"schemas":{"CHUID":{"description":"This is the model of a CHUID block for a PIV card. The only difference between this and a\nPIV-I card is the FASC-N.\n","type":"object","required":["hash","fascn"],"properties":{"hash":{"type":"string","description":"This is the hash of the CHUID object, Base64-encoded. For a 256-bit hash it\nshould be 44 characters long including one `=` pad. The API will reject a string that is\nnot valid Base64, but it will not verify the hash.\n\nRequired when creating a PIV card in versions up to 8.60. Optional in 8.70 and later.\n"},"fascn":{"type":"string","description":"This is the FASC-N identifier. You must supply it when creating a card.\n\nIt must be the same as the card number on a PIV (not PIV-I) card.\n\nOn a PIV-I card, it must not be the same as the card number (and for Federal PIV-I cards\nit will likely begin with fourteen nines).\n"},"orgIdentifier":{"type":"string","description":"Optional."},"duns":{"type":"string","description":"Optional."}}}}},"paths":{"/api/cardholders/{id} [PIV]":{"get":{"tags":["PIV cards"],"summary":"Get details of a PIV cardholder","description":"You will receive this URL from other calls to the API, in a search result or an access group\nmembership list, for example. The URL is the unique identifier of a cardholder, and calling\nit returns much of what Command Centre holds for that person, including assigned cards.\n\nThe result includes an array called `cards`. Each element of that array is a credential of\nsome type. If it is a PIV card, it will look like the example here.\n\nNote that this example is an array of one.\n\nOnly the PIV card schema is shown below. The [main\ndocumentation](cardholders#get-api-cardholders-id-) covers all the other\nfields Command Centre holds for a cardholder.\n","parameters":[{"$ref":"#/components/parameters/id"}],"responses":{"200":{"description":"Success.\n","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"array","items":{"type":"object","description":"In addition to the generic card data the API always returns in the cards\nsection (in the [Cardholders API\ndocument](cardholders.html#definition-CardholderCard)) of a cardholder\ndetail page, including `href`, `number`, `issueLevel`, `type`, and `status`,\nPIV cards have a `pivData` structure.\n\nIn version 8.00 and later `credentialClass` will have the value `piv`.\n","properties":{"href":{"type":"string","format":"uri-reference","description":"This is the same as the href to a card of any other type: you can send\nan HTTP DELETE to it to delete the card, but that is the only verb that\nwill work. GET will return a 404.\n\nDo not specify it when creating a card, since it is the creation process\nthat generates it.\n"},"number":{"type":"string","description":"While the card number rules on a PIV or PIV-I card type are different from those on other\ntypes, card numbers are still strings, and the API will accept them from you and return\nthem to you in the same way.\n\nPIV card numbers are the FASC-N with hyphens splitting the major components.\n\nPIV-I card numbers are the CHUID's GUID in decimal.\n"},"issueLevel":{"type":"integer","description":"A PIV card's issue level is derived from data in the CHUID block,\npresented here for convenience.\n"},"status":{"type":"object","properties":{"value":{"type":"string"},"type":{"type":"string"}},"description":"PIV cards have more inactive card states than other cards. 'Time\nInvalid (PIV certificate)' or 'Not Trusted', for example. If\n`status.type` is 'inactive', `status.value` will give an indication why.\n\nThe status of a new card will be 'revoked' if you set the PIV status\n(which is different from the card status, note) to anything but 'normal'\nor 'offline'.\n"},"pivData":{"description":"This is much like the [pivData](models#newpivcard) you send when\ncreating a card except that:\n\n - in certain cases (described below) it does not contain the\n certificates and biometrics, leaving just the\n [CHUID](models#chuid) block (a subset of the card's CHUID) and\n the PIV status, and\n\n - it adds `lastCheckTime`, which shows when the card was last\n validated. That is most useful when Command Centre is performing\n periodic card validation. If you are doing your own validation,\n this field will hold the moment you last updated the card.\n\nIf the site is running 7.90 and the RESTPIVCardExport customisation, or\nif it is running a later version and you asked for extra data using the\n`fields` query parameter, the `pivData` section will contain three\ncertificates and the fingerprint templates in the correct format for\nimport into another installation of Command Centre.\n\nThe certificates and biometrics are missing from the default result set\nin the interest of efficiency: those fields are very large, and most of\nour integrations do not require them. Some are running over cellular\nnetworks, where bandwidth carries a cost. Omitting the large fields\nby default but sending them on request is a flexible compromise that\nallows integrators to build a suitable system without wastage.\n","properties":{"chuid":{"$ref":"#/components/schemas/CHUID"},"lastCheckTime":{"type":"string","format":"date-time"},"pivStatus":{"type":"object","description":"The PIV status held in the `type` field in this block is distinct from the generic card\nstatus, which is a different field outside the `pivData` block.\n\nIt is optional. If you omit it when creating a card, the card will be enabled with a status\nof \"NotChecked\", which—despite how it sounds—is a perfectly valid operating status. If\nCommand Centre is doing periodic certificate validation, the status will eventually change\n(to 'normal', all going well).\n\nYou should send this block when creating a card only if you are doing your own certificate\nvalidation.\n\nWhen updating an existing card, this is the only field it makes sense to send (specifically,\nthe `type` field inside it).\n\n`type` must be set to one of these values, based on the result of your validation:\n\n - Normal\n - Offline\n - Revoked\n - Expired\n - CertInChainRevoked\n - CertInChainExpired\n - IssuerSigCertRevoked\n - IssuerSigCertExpired\n - NotTrusted\n - PolicyError\n - OtherError\n - NotChecked\n\nIf you set it to any value except 'NotChecked', 'Normal', or 'Offline', Command Centre will consider the\ncard invalid and deactivate it regardless of what you pass as the card status. You, or\nCommand Centre's periodic certificate validation, may validate the card again later.\n","properties":{"type":{"type":"string","enum":["Normal","Offline","Revoked","Expired","CertInChainRevoked","CertInChainExpired","IssuerSigCertRevoked","IssuerSigCertExpired","NotTrusted","PolicyError","OtherError","NotChecked"]}}},"contentSigningCert":{"type":"string","description":"This is required when creating a PIV or PIV-I card. The API will reject your request if this is\nmissing or not a Base64-encoded certificate, but it will not validate the certificate itself.\n\nThis example is shortened to fit on screen. Real certificates are at least a thousand\ncharacters.\n"},"cardAuthenticationCert":{"type":"string","description":"This contains the CAK, which is necessary for the secure use of contactless cards. It is\nnot required for contact cards.\n\nOptional when creating a PIV or PIV-I card. The API will reject your request if this is\npresent and not a Base64-encoded certificate, but it will not validate the certificate itself.\n"},"pivAuthenticationCert":{"type":"string","description":"This is required when creating a PIV or PIV-I card. The API will reject your request if this is\nmissing or not a Base64-encoded certificate, but it will not validate the certificate itself.\n"},"fingerprints":{"type":"string","description":"If you send this when creating a card, it should be the cardholder's fingerprints contained in\nthe card's Cardholder Fingerprints data object with the error detection code removed: the\nwhole CBEFF structure including the CBEFF_HEADER, CBEFF_BIOMETRIC_RECORD, and\nCBEFF_SIGNATURE_BLOCK components. Refer to Section 9 of NIST Special Publication 800-76-2:\nBiometric Data Specification for Personal Identity Verification.\n\nIt is optional. The API will check that this is Base64, but will not verify that it is\nvalid biometric data.\n"}}}}}}}}}}},"404":{"description":"The operator does not have a privilege that allows reading cardholders, or there is no\ncardholder at that address.\n"}}}}}}
```
## Update a cardholder's PIV cards
> This shows how to update a cardholder's PIV cards.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"PIV cards","description":"This tag is a supplement to the main cardholder API documentation ('cardholder' is the Command\nCentre term for a user). That section describes how to add a card to an existing cardholder in\na [PATCH](cardholders#patch-api-cardholders-id-), and how to create a\ncardholder with cards in a [POST](cardholders#post-api-cardholders), but in the\ninterests of brevity its examples do not cover PIV.\n\nThe schema / models section gives you the details of the PIV part of a Command Centre card, with\nexamples of what you would submit to [create](models#newpivcard) or update one, and what\nCommand Centre will send you when you view one.\n\nThe Paths section takes those schema examples and wraps them into a\n[PATCH](cardholders#patch-api-cardholders-id-) and a\n[POST](cardholders#post-api-cardholders). The two differ only in how they wrap the card\ninto the submission body.\n\nIf your application will be assigning PIV cards to cardholders, however, the first thing it\nneeds to do is learn the value of some constants for your particular installation of Command\nCentre.\n\n### Finding the PIV card type\n\nWhen you assign any card to a cardholder, PIV or otherwise, you need to provide the identifier\nof the card type. It will vary between Command Centre installations, so you cannot use a value\nfrom another installation or these examples. It will not change while Command Centre is running\nbut it may change at upgrade, so your application should follow this process at startup.\n\nIt takes two queries and a loop:\n\n 1. `GET /api`.\n 2. If running 8.00 or earlier, follow the link at `features.cardTypes.cardTypes.href` (which\n will be to `/api/card_types`), or\n 2. if running 8.10 or later, follow the link at `features.cardTypes.assign.href` (which will\n probably be to `/api/card_types/assign`. Both URLs will work in 8.10, but the advantage of\n this URL is that your operator can access it at a lower privilege level).\n 3. Iterate through the array to find the element with `credentialClass: piv`, and\n 4. note its `href`.\n\nYou can accomplish the last two steps with the JSONPath filter\n\n`$.results[?(@.credentialClass=='piv')].href`.\n\nExplanation: Command Centre ships with a handful of card types, and administrators can add\nmore, but the one that Command Centre uses for PIV and PIV-I cards has its own credential class.\nIt will look like the example in the [GET](piv-cards#get-api-cardholders-card-type).\n\n### Finding the URL to create cardholders\n\n`GET /api`. The link is at `features.cardholders.cardholders.href`.\n\n### Finding the URL of a cardholder\n\nSee the main cardholder documentation, particularly the section on [searching\ncardholders](cardholders#get-api-cardholders).\n\n### Licensing\n\nAll of the API calls described here require the RESTCardholders licence. If your site is also\nlicensed to use PIV cards, you can access those cards via REST.\n"}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"schemas":{"NewPIVCard":{"title":"New PIV Card","description":"A new PIV card. You would put this in the `cards` array of a cardholder you were creating with a POST,\nor the `cards.add` array of a cardholder you were modifying with a PATCH.\n","type":"object","required":["type","number","pivData"],"properties":{"type":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference","description":"The href of the server's PIV card type. This documentation has a section called\n\"finding the PIV card type\" if you need it.\n"}}},"status":{"type":"object","properties":{"value":{"type":"string"}}},"number":{"type":"string","description":"While the card number rules on a PIV or PIV-I card type are different from those on other\ntypes, card numbers are still strings, and the API will accept them from you and return\nthem to you in the same way.\n\nPIV card numbers are the FASC-N with hyphens splitting the major components.\n\nPIV-I card numbers are the CHUID's GUID in decimal.\n"},"pivData":{"type":"object","description":"These are the PIV-specific fields that you can set on a new card. They\nare the same as you [receive from the API](piv-cards#get-api-cardholders-id-%20-PIV-) for\nan existing PIV card except that you do not send a `lastCheckTime`.\n","required":["chuid","contentSigningCert","pivAuthenticationCert"],"properties":{"chuid":{"description":"Required when creating a card, ignored when updating one.\n\nThe FASC-N in the `chuid` block, and its relationship with the card number, is the only\ndifference between PIV and PIV-I cards in Command Centre.\n","$ref":"#/components/schemas/CHUID"},"pivStatus":{"type":"object","description":"The PIV status held in the `type` field in this block is distinct from the generic card\nstatus, which is a different field outside the `pivData` block.\n\nIt is optional. If you omit it when creating a card, the card will be enabled with a status\nof \"NotChecked\", which—despite how it sounds—is a perfectly valid operating status. If\nCommand Centre is doing periodic certificate validation, the status will eventually change\n(to 'normal', all going well).\n\nYou should send this block when creating a card only if you are doing your own certificate\nvalidation.\n\nWhen updating an existing card, this is the only field it makes sense to send (specifically,\nthe `type` field inside it).\n\n`type` must be set to one of these values, based on the result of your validation:\n\n - Normal\n - Offline\n - Revoked\n - Expired\n - CertInChainRevoked\n - CertInChainExpired\n - IssuerSigCertRevoked\n - IssuerSigCertExpired\n - NotTrusted\n - PolicyError\n - OtherError\n - NotChecked\n\nIf you set it to any value except 'NotChecked', 'Normal', or 'Offline', Command Centre will consider the\ncard invalid and deactivate it regardless of what you pass as the card status. You, or\nCommand Centre's periodic certificate validation, may validate the card again later.\n","properties":{"type":{"type":"string","enum":["Normal","Offline","Revoked","Expired","CertInChainRevoked","CertInChainExpired","IssuerSigCertRevoked","IssuerSigCertExpired","NotTrusted","PolicyError","OtherError","NotChecked"]}}},"contentSigningCert":{"type":"string","description":"This is required when creating a PIV or PIV-I card. The API will reject your request if this is\nmissing or not a Base64-encoded certificate, but it will not validate the certificate itself.\n\nThis example is shortened to fit on screen. Real certificates are at least a thousand\ncharacters.\n"},"cardAuthenticationCert":{"type":"string","description":"This contains the CAK, which is necessary for the secure use of contactless cards. It is\nnot required for contact cards.\n\nOptional when creating a PIV or PIV-I card. The API will reject your request if this is\npresent and not a Base64-encoded certificate, but it will not validate the certificate itself.\n"},"pivAuthenticationCert":{"type":"string","description":"This is required when creating a PIV or PIV-I card. The API will reject your request if this is\nmissing or not a Base64-encoded certificate, but it will not validate the certificate itself.\n"},"fingerprints":{"type":"string","description":"If you send this when creating a card, it should be the cardholder's fingerprints contained in\nthe card's Cardholder Fingerprints data object with the error detection code removed: the\nwhole CBEFF structure including the CBEFF_HEADER, CBEFF_BIOMETRIC_RECORD, and\nCBEFF_SIGNATURE_BLOCK components. Refer to Section 9 of NIST Special Publication 800-76-2:\nBiometric Data Specification for Personal Identity Verification.\n\nIt is optional. The API will check that this is Base64, but will not verify that it is\nvalid biometric data.\n"}}}}},"CHUID":{"description":"This is the model of a CHUID block for a PIV card. The only difference between this and a\nPIV-I card is the FASC-N.\n","type":"object","required":["hash","fascn"],"properties":{"hash":{"type":"string","description":"This is the hash of the CHUID object, Base64-encoded. For a 256-bit hash it\nshould be 44 characters long including one `=` pad. The API will reject a string that is\nnot valid Base64, but it will not verify the hash.\n\nRequired when creating a PIV card in versions up to 8.60. Optional in 8.70 and later.\n"},"fascn":{"type":"string","description":"This is the FASC-N identifier. You must supply it when creating a card.\n\nIt must be the same as the card number on a PIV (not PIV-I) card.\n\nOn a PIV-I card, it must not be the same as the card number (and for Federal PIV-I cards\nit will likely begin with fourteen nines).\n"},"orgIdentifier":{"type":"string","description":"Optional."},"duns":{"type":"string","description":"Optional."}}}}},"paths":{"/api/cardholders/{id} [PIV]":{"patch":{"tags":["PIV cards"],"summary":"Update a cardholder's PIV cards","description":"This shows how to update a cardholder's PIV cards.\n","requestBody":{"description":"To update a cardholder's cards or give them a new one, send an object called `cards`\ncontaining up to three arrays named 'add', 'update', and 'remove'. Every element you put\nin those arrays should be in the card schema shown here.\n","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"object","properties":{"add":{"type":"array","description":"An array of new cards to give to the cardholder.\n","items":{"$ref":"#/components/schemas/NewPIVCard"}},"update":{"type":"array","items":{"type":"object","required":["href"],"properties":{"href":{"type":"string","format":"uri-reference"},"status":{"type":"object","properties":{"value":{"type":"string"}}},"pivData":{"type":"object","description":"The only field you can change in this block is `pivStatus.type`.\n","properties":{"pivStatus":{"type":"object","properties":{"type":{"type":"string"}}}}}}}},"remove":{"type":"array","description":"To remove a card you must send its href, and you may send a new status.\n","items":{"type":"object","required":["href"],"properties":{"href":{"type":"string","format":"uri-reference"},"status":{"type":"object","properties":{"value":{"type":"string"}}}}}}}}}}}},"required":true},"responses":{"200":{"description":"Success. Future versions will add feedback from the server about your PATCH.\n"},"204":{"description":"Success, with no feedback."},"400":{"description":"The parameters are invalid, or other errors prevented the update.\n"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.security.gallagher.com/knowledge-hub/developer/rest-api/piv-cards.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.