# Obtain the list of signature credentials of the user

# Alias

`CscCredentialsList`

# Description

Provides the list of signature credentials (i.e., signing identities) of a user.

# Request

To obtain a user's list of signing identities, the client application must send the following request to the TRIDENT using TLS.

`POST /trustedx-resources/csc/v2/credentials/list`
Important

[CSC_STANDARD_V2] requires that the base path of all requests of the access API to a remote signature services provider be `/csc/v2/`. Thus, if the TRIDENT administrator decides to follow the standard strictly, they must deploy the system so that the base path of the request is `/csc/v2` instead of`/trustedx-resources/csc/v2`. To determine if this is the case in your situation, check the "`oauth2`" property of the JSON object provided by the Obtain information on the CSC signature service operation.

## Content-Type Header

`Content-Type: application/json`

## Request Parameters

Name | Type | Usage | Description
`userID` | String | Conditionally required | Identifier of the user whose signature credentials list is to be obtained. This parameter can only be used (and must be used in this case) when the access token demonstrating the authorization is a bearer OAuth 2.0 token obtained in a Client Credentials Grant authorization flow, I.e., when the access token is not for an authorization granted by a user in particular.
`credentialInfo` | Boolean | Optional | Request to return the main information included in the public key certificate, the public key certificate itself, or the certificate chain associated with the credentials. The default value is `false`, so if the parameter is omitted, the information will not be returned.
`certificates` | String | Conditionally optional | Specifies which certificates from the certificate chain shall be returned in `cert/certificates.` Only the following values are allowed: `"none"`: No certificate shall be returned. `"single"`: Only the end entity certificate shall be returned. `"chain"`: The full certificate chain shall be returned. The `"single"` value is the default, so if the parameter is omitted, the method will only return the user's certificates. This parameter may be specified only if the parameter `credentialInfo` is `true`. If the parameter `credentialInfo` is not `true` and this parameter is specified, its value will be ignored.
`certInfo` | Boolean | Conditionally optional | Request to return various parameters containing information from the user certificates. This is useful in case the signature application wants to retrieve some details of the certificates without having to decode them first. The default value is `false`, so the information will not be returned if the parameter is omitted. This parameter may be specified only if the parameter `credentialInfo` is `true`. If the parameter `credentialInfo` is not `true` and this parameter is specified, its value will be ignored.

## Authorization

The request must contain a bearer access token with the `service` scope. As a rule, obtaining this token via either an authorization code grant or client credentials grant OAuth 2.0 flow is possible. When the token is obtained through an OAuth 2.0 Authorization Code Grant, the user whose credentials list is requested is implicit in the token, so the `userID` request parameter should not be used.

The access token must be put in the `Authorization` header, as explained in RFC 6750. I.e., as follows:

`Authorization: Bearer <token>`

# Response

## Status-Line

If the request is successfully processed, the HTTP response contains the following `Status-Line``:`

`HTTP/1.1 200 OK`

## Content-Type Header

`Content-Type: application/json;charset=UTF-8`

## Body

JSON object that contains the list of signature credentials of a user.

`{`
`"credentialIDs" : [{string}]`
`"credentialInfos": : [{credentialInfo}]`
`}`

Property | Type | Description
`credentialIDs` | String Array | Identifiers of the signature credentials of the user specified in the `userID` parameter of the request or associated with the access token included in the request.
`credentialInfos` | CredentialInfo Array | An array of the JSON objects, each one with the following structure: `{` `"credentialID": {string},` `<info_regarding_the_credentialID_credential>` `}` where `credentialID` is the identifier of one of the credentials whose data is included in the list, and `<info_regarding_the_credentialID_credential>` refers to the information returned for this credential and consists of the same attributes as the JSON object returned by the Obtain a signature credential of a user operation.

# Error Management

If the request does not contain the `Authorization: Bearer` header, the TRIDENT returns an HTTP response with the 401 Unauthorized `Status Code`.

If the request is not successfully processed, the TRIDENT returns an HTTP error response with the `Content-Type: application/json;charset=utf-8` header and a JSON object in the body with the following properties:

- `error`: Error code.

- `error_description`: Additional description of the error. Not required.

Error Case | Status Code (HTTP) | error | error_description
The `userID` parameter was included in the request, and the request's access token is associated with the user (i.e., the access was authorized by a specific user). | 400 Bad Request | `invalid_request` | `invalidUserId`
The `userID` parameter was not included in the request, and the request's access token is associated with the application. Or the `userID` parameter was included, but the user specified does not exist. | 400 Bad Request | `invalid_request` | `invalidParameter`

# Example

## Request

The signature application requests the list of signature credentials of the user identified by `john.doe@corporation.com`. For this, it sends the following request to the TRIDENT and includes in it an access token with the service scope obtained in a Client Credentials Grant OAuth 2.0 authorization flow.

`POST /trustedx-resources/csc/v2/credentials/list HTTP/1.1`
`Host: rse.corporation.com`
`Authorization: Bearer 9ade1210b7ac648b49defc577aa258eb2701b2064a14de13842524c2fd59c597`
`Content-Type: application/json`
`{`
`"userID": "john.doe@corporation.com",`
`"credentialInfo": true,`
`"certificates": "single",`
`"certInfo": true`
`}`

## Response

The TRIDENT responds to the signature application, providing it with the following information regarding signature credentials of the `john.doe@corporation.com` user.

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=UTF-8`
`{`
`"credentialIDs": ["m9jttphq6hpucr986si4hpc4e7", "g9iiilht5hwevt986si4hpc5y6"]`
`"credentialInfos": [`
`{`
`"credentialID": "m9jttphq6hpucr986si4hpc4e7"`
`"description": "Corporative signature credential",`
`"key": {`
`"status": "enabled",`
`"algo": [`
`"1.2.840.113549.1.1.13",`
`"1.2.840.113549.1.1.1",`
`"1.2.840.113549.1.1.11",`
`"1.2.840.113549.1.1.12"`
`],`
`"len": 2048`
`},`
`"cert": {`
`"certificates": ["MIIFpTCCBI2...m1SEW"],`
`"serialNumber": "67210661094051074244364068313147966416",`
`"validFrom": "20240116121230Z",`
`"validTo": "20250116121230Z",`
`"issuerDN": "CN=Entrust QA (SML) Class 3 Client CA - SHA256, OU=\"(c) 2015 Entrust, Inc. - for authorized use only\",`
`OU=See www.entrust.net/legal-terms, O=\"Entrust, Inc.\", C=US",`
`"subjectDN": "CN=John Doe, O=Corporation, L=Otwaw, ST=Ontario, C=CA"`
`},`
`"authMode": "oauth2code",`
`"multisign": 40,`
`"lang": "en-US",`
`"SCAL": "2"`
`},`
`{`
`"credentialID": "g9iiilht5hwevt986si4hpc5y6"`
`"description": "Corporative signature credential",`
`"key": {`
`"status": "disabled",`
`"algo": [`
`"1.2.840.113549.1.1.13",`
`"1.2.840.113549.1.1.1",`
`"1.2.840.113549.1.1.11",`
`"1.2.840.113549.1.1.12"`
`],`
`"len": 2048`
`},`
`"cert": {`
`"certificates": ["MIIFpTCCBI2...n2TXk"],`
`"serialNumber": "74376598109984627484011099193246767690",`
`"validFrom": "20230116121230Z",`
`"validTo": "20240116121230Z",`
`"issuerDN": "CN=Entrust QA (SML) Class 3 Client CA - SHA256, OU=\"(c) 2015 Entrust, Inc. - for authorized use only\",`
`OU=See www.entrust.net/legal-terms, O=\"Entrust, Inc.\", C=US",`
`"subjectDN": "CN=John Doe, O=Corporation, L=Otwaw, ST=Ontario, C=CA"`
`},`
`"authMode": "oauth2code",`
`"multisign": 40,`
`"lang": "en-US",`
`"SCAL": "2"`
`}`
`}`