Credential REST API

The Credential endpoint allows creating and managing credentials used to authenticate users.

Credentials are stored in devices and contain information used to authenticate users, and are linked to a credential type which defines the credential parameters leveraged during user authentication.

Note: The API version supported by HID Authentication Service is 10.3.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality. For details of the version updates, see SCIM API Revision History.

Method Details

HTTPS Method	Entity Action	Request URI	Description
GET	Read	/scim/{tenant}/v2/Credential	Retrieve credentials filtered by attributes
GET	Read	/scim/{tenant}/v2/Credential/{id}:(String)	Retrieve a known credential
POST	Search	/scim/{tenant}/v2/Credential/.search	Search for credential
PUT	Replace	/scim/{tenant}/v2/Credential/{id}:(String)	Fully replace a known credential
DELETE	Delete	/scim/{tenant}/v2/Credential/{id}:(String)	Delete a known credential

Required Permissions

Function	Required Permissions
GET	Read credential details
REPLACE	Update credential Set credential status Read credential details Read reference data
DELETE	Read credential details Delete credential
SEARCH	If the 'owner.value' filter is used: Read device details Read credential details Else: Search credentials Search users

Get a Credential

[GET] /Credential/{id}

Copy

Sample Request URI

[GET] /scim/{tenant}/v2/Credential/11385

Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:Credential"],
   "id": "11385",
   "externalId": "jdoeCT_ACODE",
   "meta":    {
      "resourceType": "Credential",
      "location": "https://[base-server-url]/scim/tenant/v2/Credential/11385",
      "version": "1"
   },
   "type": "CT_ACODE",
   "status":    {
      "status": "ACTIVE",
      "active": true,
      "expiryDate": "2018-11-21T14:14:59Z"
   },
   "attributes":    [
            {
         "name": "MY_ATTR0",
         "type": "string",
         "value": "value0",
         "readOnly": false
      },
            {
         "name": "MY_ATTR1",
         "type": "string",
         "value": "value1",
         "readOnly": false
      },
            {
         "name": "EXPIRY_THRESHOLD_OF_ACTIVATION_CODE",
         "type": "string",
         "value": "-1",
         "readOnly": false
      }
   ],
   "totalUsed": "0"
}

Replace a Credential

[PUT] /Credential/{id}

Accept: application/scim+json

Note: As a best practice, use GET to retrieve the current data for the resource before using PUT.

Updatable attributes:

status.status
attributes

Current Status	Possible Transition
PENDING	ACTIVE
ACTIVE	SUSPENDED, REVOKED
SUSPENDED	ACTIVE, REVOKED
REVOKED	TERMINATED

Note:

If attributes is not present in the request, its content will be deleted

Copy

Sample Request URI

[PUT] /scim/{tenant}/v2/Credential/11385

Copy

Sample Request to update the credential from the previous GET Credential sample. The updates are:

Attribute MY-ATTR0 is removed
Attribute MY-ATTR1 value is changed

{
   "schemas": ["urn:hid:scim:api:idp:2.0:Credential"],
   "id": "11385",
   "externalId": "jdoeCT_ACODE",
   "meta":    {
      "resourceType": "Credential",
      "created": "2017-11-21T13:58:40Z",
      "location": "https://[base-server-url]/scim/tenant/v2/Credential/11385",
      "version": "1"
   },
   "type": "CT_ACODE",
   "status":    {
      "status": "ACTIVE",
      "active": true,
      "expiryDate": "2018-11-21T13:58:40Z",
      "startDate": "2017-11-21T13:58:40Z"
   },
   "attributes": [   {
      "name": "EXPIRY_THRESHOLD_OF_ACTIVATION_CODE",
      "type": "string",
      "value": "-1",
      "readOnly": false
   },
   {
      "name": "MY_ATTR1",
      "type": "string",
      "value": "new value",
      "readOnly": false
   }],
   "totalUsed": "0"
}

Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:Credential"],
   "id": "11385",
   "externalId": "jdoeCT_ACODE",
   "meta":    {
      "resourceType": "Credential",
      "location": "https://[base-server-url]/scim/tenant/v2/Credential/11385",
      "version": "1"
   },
   "type": "CT_ACODE",
   "status":    {
      "status": "ACTIVE",
      "active": true,
      "expiryDate": "2018-11-21T14:16:07Z"
   },
   "attributes":    [
            {
         "name": "MY_ATTR1",
         "type": "string",
         "value": "new value",
         "readOnly": false
      },
            {
         "name": "EXPIRY_THRESHOLD_OF_ACTIVATION_CODE",
         "type": "string",
         "value": "-1",
         "readOnly": false
      }
   ],
   "totalUsed": "0"
}

Search for a Credential

Supported search criteria are:

SCIM Attribute	Operators supported
type	eq
externalid	eq
id	eq
status.expiryDate	eq, gt, lt
status.status	eq

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Credential/.search

Copy

Sample Request

[POST] /scim/{tenant}/v2/Credential/.search
{
 "filter": "externalid eq jsmith",
}

Where the filter attribute can be used to reduce the number of records you want to see.

You can use the and operator within the filters.

Note: For further information, see Searching with the SCIM API.

Delete a Credential

All the delete endpoints follow the same standard pattern and can be reached through the following URL pattern:

Copy

Delete entity

DELETE https://[base-server-url]/scim/{tenant}/v2/ENTITY_TYPE/{id}

Accept: application/scim+json

Copy

Sample Response

HTTP/1.1 204 No content