7 Administration Service

This chapter describes the Administration Service.

createClient — POST

This section describes the createClient endpoint. This service creates a new application client that can be used to call CaR services from another application.

Method

POST

URL

/api/admin/v1/client

Allowed Scope(s)

admin-rw

Request

There are no request parameters.

The request body is application/json.

The ModelField request.

Example Value

{
  "scopes": [
    "string"
  ],
  "appDescription": "string"
}
Schema — Client Request

The following table describes details of the new client.

Table 7-1 Client Request — Object

Element Name Required Data Type Description
scopes NA string A collection of scopes assignment.
admin NA boolean Indicates if the client is an administrator.
appDescription NA string App description

Responses

This section describes the responses of the createClient endpoint.

Response Code: 200

The result object.

The media type is application/json.

Example Value

{
  "scopes": [
    "string"
  ],
  "clientId": "string",
  "clientSecret": "string"
}
Schema — Client Response

The following table describes the elements of a response to the create client request.

Table 7-2 Client Response — Object

Element Name Required Data Type Description
scopes NA string A collection of assigned scopes.
clientId NA string Client Id
clientSecret NA string Client secret
Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]
Schema — Mapper Error Data

The table below describes the elements of the Mapper Error Data object.

Table 7-3 Mapper Error Data — Object

Element Name Required Data Type Description

column

 NA

integer <int32>

The JSON file column number the error occurred on if known

line

 NA

integer <int32>

The JSON file line number the error occurred on if known

errorCode

 NA

integer <int32>

A numeric identifier for the type of error

errorMessage

 NA

string

The unlocalized error message

moreInfo

 NA

object

Additional information pertaining to the error

field

 NA

string

The field. This is the last part of the path

value

 NA

string

The JSON value that caused the error if known

errorType

 NA

string

enum: INTEGRATION, INTERNAL, MAPPING, PARSING, VALIDATION An enumeration of specific known error types.

The following table describes the elements of the additional information pertaining to the error.

Table 7-4 More Info — Object

Element Name Required Data Type Description

code

 NA

string

A code describing the error.

description

 NA

string

An unlocalizable description describing the error.
Response Code: 424

Cannot generate new client.

Response Code: 500

The request failed.

forgetPrivateData — POST

This section describes the forgetPrivateData endpoint. Use this service to validate if data is eligible to be anonymized. This includes address information, name, phone, and e-mail. Additionally, use this service to anonymize all personal data stored in the database for the parameters specified.

Method

POST

URL

/api/admin/v1/privacy

Allowed Scope(s)

private-rw

Request

This section describes the request parameters.

Table 7-5 forgetPrivateData — Request Parameters

Parameter Required Data Type Description
identifier Yes string (query)

The type of private data identifier.

Available values : CONTACT_REFERENCE, EMAIL_ADDRESS, LOCATION, PHONE_NUMBER
value Yes string (query) The value corresponding to the private data identifier.
checkOnly Yes boolean (query) An indication that the request should verify the ability to delete, but not delete data.

Responses

This section describes the responses of the forgetPrivateData endpoint.

Response Code: 200

The number of records affected, or to be affected if checkOnly is true, by the call.

The media type is application/json.

Response Code: 204

No records were found matching the supplied criteria.

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]
Schema — Mapper Error Data

For more information about the schema Mapper Error Data, see the Schema — Mapper Error Data section.

Response Code: 409

Dependent data exists which prevents the request from being completed.

Response Code: 500

The request failed.

getPrivateData — GET

This section describes the getPrivateData endpoint. This service retrieves the PII data based on the parameters used in the request.

Method

GET

URL

/api/admin/v1/privacy

Allowed Scope(s)

private-rw

Request

This section describes the request parameters.

Table 7-6 getPrivateData — Request Parameters

Parameter Required Data Type Description
identifier Yes string (query)

The type of private data identifier.

Available values : CONTACT_REFERENCE, EMAIL_ADDRESS, LOCATION, PHONE_NUMBER
value Yes string (query) The value corresponding to the private data identifier.

Responses

This section describes the responses of the getPrivateData endpoint.

Response Code: 200

The result object.

The media type is application/json.

Example Value

[
  {
    "address1": "string",
    "address2": "string",
    "address3": "string",
    "address4": "string",
    "apartment": "string",
    "businessName": "string",
    "city": "string",
    "contactReference": "string",
    "country": "string",
    "emailAddress": "string",
    "firstName": "string",
    "lastName": "string",
    "latitude": 999999999,
    "longitude": 999999999,
    "middleName": "string",
    "phoneNumber": "string",
    "postalCode": "string",
    "state": "string",
    "suffix": "string",
    "usages": [
      "DROPOFF"
    ]
  }
]
Schema — Private Data Result

The following table describes the elements of the result data for a private data request.

Table 7-7 Private Data Result — Object

Element Name Required Data Type Description
address1 NA string(254) The address line 1.
address2 NA string(254) The address line 2.
address3 NA string(254) The address line 3.
address4 NA string(254) The address line 4.
apartment NA string(254) The apartment
businessName NA string(254) The business name.
city NA string(254) The city or town.
contactReference NA string(64) A reference number for the contact.
country NA string(254) The ISO-3166 country code. Applications can decide whether to use 2 or 3 char codes.
emailAddress NA string(254) The email address.
firstName NA string(254) The first name (given) name.
lastName NA string(254) The last name (family) name.
latitude NA number The latitude of the address.
longitude NA number The longitude of the address.
middleName NA string(254) The middle name.
phoneNumber NA string(50) The phone number.
postalCode NA string(20) The postal code.
state NA string(254) The ISO 3166 state, province or territory code.
suffix NA string(254) A name suffix.
usages NA string The location(s) in which the data was found to be in-use. Enum: DROPOFF, PICKUP, LOCATION
Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]
Schema — Mapper Error Data

For more information about the schema Mapper Error Data, see the Schema — Mapper Error Data section.

Response Code: 500

The request failed.

addScopes — PUT

This section describes the addScopes endpoint. This API adds a set of scopes to an IDCS client.

Method

PUT

URL

/api/admin/v1/scope/{appName}

Allowed Scope(s)

admin-rw

Request

This section describes the request parameters.

Table 7-8 addScopes— Request Parameters

Parameter Required Data Type Description
appName Yes string (path)

The IDCS client's display name.

Responses

This section describes the responses of the addScopes endpoint.

Response Code: 204

The request was successful.

Response Code: 400

The provided input is invalid.

The media type is application/json.

Example Value

[
  {
    "column": 0,
    "line": 0,
    "errorCode": 0,
    "errorMessage": "string",
    "moreInfo": {
      "code": "string",
      "description": "string"
    },
    "field": "string",
    "value": "string",
    "errorType": "INTEGRATION"
  }
]
Schema — Mapper Error Data

For more information about the schema Mapper Error Data, see the Schema — Mapper Error Data section.

Response Code: 404

IDCS client not found.

Response Code: 424

IDCS request failed.

Response Code: 500

The request failed.

getClients— GET

This section describes the getClients endpoint. This API obtains a list of IDCS clients with a CaR scope for the tenant environment.

Method

GET

URL

/api/admin/v1/scope/client

Allowed Scope(s)

admin-r

Request

There are no request parameters.

Responses

This section describes the responses of the getClients endpoint.

Response Code: 200

List of IDCS clients.

The media type is application/json.

Example Value

[
  {
    "created": "2024-11-28T14:46:46.687Z",
    "grantedScopes": [
      "string"
    ],
    "id": "string",
    "name": "string",
    "updated": "2024-11-28T14:46:46.687Z"
  }
]
Schema — Client

Table 7-9 — Client

Element Name Required Data Type Description

created

NA

string($date-time)

Date time when the client was created.

grantedScopes

NA

uniqueItems: true string

Granted scopes to the client.

id

NA

string

The IDCS client identifier.

name

NA

string

The IDCS client name.

updated

NA

string($date-time)

Date time when the client was last updated.
Response Code: 404

No CaR clients found.

Response Code: 424

IDCS request failed.

Response Code: 500

The request failed.