API Reference > Part II: Authenticate using JWT > Manage orders and consumer accesses > Consumer accesses
  

Consumer accesses

A consumer access is a record that indicates a Data User's access to a data collection, along with other details such as the date of delivery, details of the stakeholder that delivered the data, and the delivery option that was used for the delivery.

Create consumer accesses

Use a REST API to create a consumer access in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v2/consumer-accesses
Method
POST
For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the body of the API payload:
Parameter
Description
Additional Information
externalId
Optional. Enter a reference identifier for the consumer access that you want to create.
If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the item. The reference identifier that Data Marketplace automatically generates contains a prefix. The administrator can specify the prefix of the automatically generated reference identifier in Metadata Command Center.
If you want to specify a reference identifier, ensure that you enter a unique value. Ensure that you don't use the prefix value that is configured in Metadata Command Center.
status
Optional. Specify a status for the consumer access.
Enter one of the following values:
  • - For a consumer access where the Data User has access to the data collection, enter AVAILABLE.
  • - For a consumer access that is awaiting withdrawal, enter PENDING_WITHDRAW.
  • - For a consumer access that is withdrawn, enter WITHDRAWN.
Default value is AVAILABLE.
-
dataCollectionId
Required. Enter the system-generated unique identifier of the data collection to which the Data User was granted access.
For more information about how you can use an API to get the system-generated unique identifier of a data collection, see Retrieve all data collections.
To get the system-generated unique identifier of a data collection from the Data Marketplace user interface, open the data collection. The data collection page's URL contains the unique identifier.
For example, in the URL https://{{CDMP_URL}}/datacollection/25158afc-3dfb-44ef-8f3e-cec1e171d0f1?dtn=&tab=summary, the unique identifier is 25158afc-3dfb-44ef-8f3e-cec1e171d0f1.
deliveryTargetId
Required. Enter the system-generated unique identifier of the delivery target that was used to deliver the data.
For more information about how you can use an API to get the system-generated unique identifier of a delivery target, see Retrieve all delivery targets.
accessGrantedOn
Optional. Enter the date on which the Data User was granted access to the data collection.
To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard.
consumerUserId
Required. Enter the system-generated unique identifier of the user account that was granted access to the data collection.
To get the system-generated unique identifier of a user account, navigate to My Services > Administrator > Users. On the Users page, click a user account. The user account page's URL contains the unique identifier.
For example, in the URL /cloudUI/products/administer/main/usersAsset/0LH3xBJC9A6haZ26htGZyT, the unique identifier is 0LH3xBJC9A6haZ26htGZyT.
usageContextId
Optional. Enter the system-generated unique identifier of the usage type used to specify the context in which the data is to be used as provided by the Data User that was granted access to the collection.
For more information about how you can use an API to get the system-generated unique identifier of a usage type, see Retrieve usage type.
costCenter
Optional. Enter the cost center of the Data User that was granted access to the data collection.
-
customAttributes
Specify the custom attribute values for the consumer access.
Whether you must enter a value or not enter a value in a custom attribute is determined by how the custom attribute was defined by your administrator in Metadata Command Center.
Custom attributes are additional properties for Data Marketplace items that are defined by your administrator in Metadata Command Center. For more information about custom attributes, see the Create custom attributes for items topic in the Set Up Data Marketplace help.
customAttributes > value
Enter a value in the custom attribute.
-
customFields > id
Enter the system-generated unique identifier of the custom attribute.
For more information about how you can retrieve the system-generated unique identifier of a custom attribute, see Retrieve custom attributes.

Example request

The following example shows how you can use an API to create a consumer access:
{
"externalId": "CAS-123",
"status": "AVAILABLE",
"dataCollectionId": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"deliveryTargetId": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"accessGrantedOn": "2025-08-01",
"consumerUserId": "jqPFaKmJRGhdfJ35eWUzoW",
"usageContextId": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"costCenter": "string",
"customAttributes": [
{
"value": "PROJ-2024-CUSTOMER-INSIGHTS",
"id": "com.infa.odin.models.custom.ca_2491832487117218775"
}
]
}

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.
The following example shows the response of an API call to create a consumer access:
{
"id": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"externalId": "CAS-123",
"costCenter": "IT-DEPT-001",
"status": "AVAILABLE",
"accessGrantedOn": "2025-08-01",
"consumer":
{
"stakeholderId": "jaXM6NrqsKXffdwg2NkTMR",
"userType": "USER",
"roleId": "Stakeholder_Role_Marketplace_Editor",
"isInherited": false
},
"assetGroups": [
{
"id": "c1a86a0e-7690-4577-99ab-be4b193e7d90",
"name": "ASIA",
"isInherited": true
}
]
}
The following table describes the parameters of each consumer access that is created:
Parameter
Description
id
System-generated unique identifier of the consumer access.
externalId
Reference identifier of the consumer access.
costCenter
Cost center of the Data User that was granted access to the data collection.
status
Status of the consumer access.
A consumer access can have the following statuses:
  • - AVAILABLE. The Data User has access to the data collection.
  • - PENDING_WITHDRAW. A request is submitted to withdraw the Data User's access to the data collection.
  • - WITHDRAWN. The Data User's access to the data collection is withdrawn.
accessGrantedOn
Date on which the Data User was granted access to the data collection.
consumer
Details about the Data User that was granted access to the data collection.
assetGroups
Details of the asset group that is assigned to the category that contains the data collection that is associated with the consumer access.
assetGroups > id
System-generated identifier of the asset group.
assetGroups > name
Name of the asset group.
assetGroups > isInherited
Indicates whether the asset group is directly assigned to the category or if the asset group is inherited from the category hierarchy.
This parameter can have one of the following values:
  • - true. The asset group is inherited from the category hierarchy.
  • - false. The asset group is directly assigned to the category.

Retrieve a consumer access

Use a REST API to retrieve the details of an individual consumer access in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v2/consumer-accesses/<consumerAccessId>
<consumerAccessId>: Required. Enter the system-generated identifier of the consumer access for which you want to retrieve the details.
For more information about how you can use an API to get the system-generated unique identifier of a consumer access, see Retrieve all consumer accesses.
To get the system-generated unique identifier of a consumer access from the Data Marketplace user interface, open the consumer access. The consumer access page's URL contains the unique identifier.
For example, in the URL https://{{CDMP_URL}}/access/e254491f-5795-49bd-be0b-385eb11d9d5a?dtn=Access~2e85, the unique identifier is e254491f-5795-49bd-be0b-385eb11d9d5a.
Method
GET
For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the request query:
Parameter
Description
Additional Information
segments
Optional. Specify the type of details that you want the API request to return.
Enter one or more of the following values:
  • - all. Returns all the details about the consumer access.
  • - customAttributes. Returns the details about the custom attributes that are configured for the consumer access.
  • - dataCollection. Returns the details about the data collection that is associated with the consumer access.
  • - deliveryTarget. Returns the details about the delivery target that was used to deliver the data.
  • - order. Returns the details about the order for which the consumer access is created.
  • - systemAttributes. Returns the details about the consumer access's creation and modification, such as the date when the consumer access was granted, the latest date when it was modified, and so on.
  • - terms. Returns the details about the terms of use snapshot that represents the state of the terms of use of the data collection when the order was placed.
  • - usageContext. Returns the details about the usage type that the Data User selected at the time of order.
By default, the parameter is assigned no value and the API response includes only the basic information about the consumer access such as status, cost center and so on.
Note: The API has no payload.

Example request

The following example shows how you can use an API to retrieve the details of a consumer access:
https://{{CDMP_URL}}/api/v2/consumer-accesses/2593524d-82f7-4dfd-bc6b-17088c046f9d

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.
The following example shows the response of an API call to retrieve the details of a consumer access:
{
"id": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"externalId": "CAS-123",
"costCenter": "IT-DEPT-001",
"status": "AVAILABLE",
"accessGrantedOn": "2025-08-01",
"consumer":
{
"stakeholderId": "jaXM6NrqsKXffdwg2NkTMR",
"userType": "USER",
"roleId": "Stakeholder_Role_Marketplace_Editor",
"isInherited": false
},
"assetGroups": [
{
"id": "c1a86a0e-7690-4577-99ab-be4b193e7d90",
"name": "ASIA",
"isInherited": true
}
]
}
The following table describes the parameters of the consumer access that is retrieved:
Parameter
Description
id
System-generated unique identifier of the consumer access.
externalId
Reference identifier of the consumer access.
costCenter
Cost center of the Data User that was granted access to the data collection.
status
Status of the consumer access.
A consumer access can have the following statuses:
  • - AVAILABLE. The Data User has access to the data collection.
  • - PENDING_WITHDRAW. A request is submitted to withdraw the Data User's access to the data collection.
  • - WITHDRAWN. The Data User's access to the data collection is withdrawn.
accessGrantedOn
Date on which the Data User was granted access to the data collection.
consumer
Details about the Data User that was granted access to the data collection.
assetGroups
Details of the asset group that is assigned to the category that contains the data collection that is associated with consumer access.
assetGroups > id
System-generated identifier of the asset group.
assetGroups > name
Name of the asset group.
assetGroups > isInherited
Indicates whether the asset group is directly assigned to the category or if the asset group is inherited from the category hierarchy.
This parameter can have one of the following values:
  • - true. The asset group is inherited from the category hierarchy.
  • - false. The asset group is directly assigned to the category.

Retrieve all consumer accesses

Use a REST API to retrieve the details of all consumer accesses in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v2/consumer-accesses
Method
GET
For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the request query:
Parameter
Description
Additional Information
offset
Optional. Specify the starting index for the paginated results.
Default value is 0.
limit
Optional. Specify the maximum number of results that are displayed on a page.
Default value is 20.
Maximum value is 200.
segments
Optional. Specify the type of details that you want the API request to return.
Enter one or more of the following values:
  • - all. Returns all the details about each consumer access that is retrieved.
  • - customAttributes. Returns the details about the custom attributes that are configured for a consumer access.
  • - dataCollection. Returns the details about the data collection that is associated with a consumer access.
  • - deliveryTarget. Returns the details about the delivery target that was used to deliver the data.
  • - order. Returns the details about the order for which the consumer access is created.
  • - usageContext. Returns the details about the usage type that the Data User selected at the time of order.
  • - terms. Returns the details about the terms of use snapshot that represents the state of the terms of use of the data collection when the order was placed.
  • - systemAttributes. Returns the details about a consumer access's creation and modification, such as the date when the consumer access was granted, the latest date when it was modified, and so on.
By default, the parameter is assigned no value and the API response includes only the basic information about the consumer access such as status, cost center and so on.
sortBy
Optional. Specify the parameters to sort the search results.
Enter one of the following values:
  • - accessGrantedOn
  • - createdOn
  • - modifiedOn
Default value is modifiedOn.
sortOrder
Optional. Set the sorting order of the search results.
Enter one of the following values:
  • - To sort the search results by ascending order, enter asc.
  • - To sort the search results by descending order, enter desc.
Default value is desc.
status
Optional. Specify the status of the consumer access.
Enter one of the following values:
  • - To find consumer accesses where the Data User has access to the data collection, enter AVAILABLE.
  • - To find consumer accesses that are pending withdrawal, enter PENDING_WITHDRAW.
  • - To find consumer accesses that are withdrawn, WITHDRAWN.
-
Note: The API has no payload.

Example request

The following example shows how you can use an API to retrieve the details of all consumer accesses:
https://{{CDMP_URL}}/api/v2/consumer-accesses

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.
The following example shows the response of an API call to retrieve the details of all consumer accesses:
{
"pageInfo": {
"offset": 40,
"limit": 20,
"totalCount": 120
},
"links": {
"self": {
"href": "/consumer-accesses?offset=40&limit=20"
},
"first": {
"href": "/consumer-accesses?offset=0&limit=20"
},
"next": {
"href": "/consumer-accesses?offset=60&limit=20"
},
"previous": {
"href": "/consumer-accesses?offset=20&limit=20"
},
"last": {
"href": "/consumer-accesses?offset=100&limit=20"
}
},
"items": [
{
"id": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"externalId": "CAS-123",
"costCenter": "IT-DEPT-001",
"status": "AVAILABLE",
"accessGrantedOn": "2025-08-01",
"consumer":
{
"stakeholderId": "jaXM6NrqsKXffdwg2NkTMR",
"userType": "USER",
"roleId": "Stakeholder_Role_Marketplace_Editor",
"isInherited": false
},
"assetGroups": [
{
"id": "c1a86a0e-7690-4577-99ab-be4b193e7d90",
"name": "ASIA",
"isInherited": true
}
]
}
]
}
The following table describes the parameters of each consumer access that is retrieved:
Parameter
Description
pageInfo > offset
Starting index of the paginated results.
pageInfo > limit
The maximum number of results that are displayed on a page.
pageInfo > totalCount
Number of consumer accesses retrieved.
links > self > href
The API that was invoked to generate this response.
links > first > href
The API endpoint that you can use to retrieve the search results that are displayed on the first page.
links > next > href
The API endpoint that you can use to retrieve the search results from the page following the one you currently have open.
links > previous > href
The API endpoint that you can use to retrieve the search results from the page prior to the one you currently have open.
links > last > href
The API endpoint that you can use to retrieve the search results that are displayed on the last page.
id
System-generated unique identifier of the consumer access.
externalId
Reference identifier of the consumer access.
costCenter
Cost center of the Data User that was granted access to the data collection.
status
Status of the consumer access.
A consumer access can have the following statuses:
  • - AVAILABLE. The Data User has access to the data collection.
  • - PENDING_WITHDRAW. A request is submitted to withdraw the Data User's access to the data collection.
  • - WITHDRAWN. The Data User's access to the data collection is withdrawn.
accessGrantedOn
Date on which the Data User was granted access to the data collection.
consumer
Details about the Data User that was granted access to the data collection.
assetGroups
Details of the asset group that is assigned to the category that contains the data collection that is associated with consumer access.
assetGroups > id
System-generated identifier of the asset group.
assetGroups > name
Name of the asset group.
assetGroups > isInherited
Indicates whether the asset group is directly assigned to the category or if the asset group is inherited from the category hierarchy.
This parameter can have one of the following values:
  • - true. The asset group is inherited from the category hierarchy.
  • - false. The asset group is directly assigned to the category.

Modify custom attributes of consumer accesses

Use a REST API to modify the custom attributes of a consumer access in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v2/consumer-accesses/<consumerAccessId>
<consumerAccessId>: Required. Enter the system-generated identifier of the consumer access whose custom attributes you want to modify.
For more information about how you can use an API to get the system-generated unique identifier of a consumer access, see Retrieve all consumer accesses.
To get the system-generated unique identifier of a consumer access from the Data Marketplace user interface, open the consumer access. The consumer access page's URL contains the unique identifier.
For example, in the URL https://{{CDMP_URL}}/access/e254491f-5795-49bd-be0b-385eb11d9d5a?dtn=Access~2e85, the unique identifier is e254491f-5795-49bd-be0b-385eb11d9d5a.
Method
PATCH
For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the body of the API payload:
Parameter
Description
Additional Information
customAttributes
Modify the custom attributes of the consumer access.
Whether you must enter a value in a custom attribute or not is determined by how the custom attribute was defined by your administrator in Metadata Command Center.
Custom attributes are additional properties for Data Marketplace items that are defined by your administrator in Metadata Command Center. For more information about custom attributes, see the Create custom attributes for items topic in the Set Up Data Marketplace help.
customAttributes > value
Enter the updated value for the custom attribute.
-
customFields > id
Enter the system-generated unique identifier of the custom attribute that you want to modify.
For more information about how you can retrieve the system-generated unique identifier of a custom attribute, see Retrieve custom attributes.

Example request

The following example shows how you can use an API to modify the custom attributes of a consumer access:
{
"customAttributes": [
{
"value": "PROJ-2024-CUSTOMER-INSIGHTS",
"id": "com.infa.odin.models.custom.ca_2491832487117218775"
}
]
}

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.
If you see the following response code, it means that the custom attributes of the consumer access are successfully modified successfully:
204 OK code

Submit consumer access withdrawals

Use a REST API to submit a request to withdraw a Data User's access to a data collection.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v2/consumer-accesses/<consumerAccessId>/request-withdrawal
<consumerAccessId>: Required. Enter the system-generated identifier of the consumer access for which you want to request a withdrawal.
For more information about how you can use an API to get the system-generated unique identifier of a consumer access, see Retrieve all consumer accesses.
To get the system-generated unique identifier of a consumer access from the Data Marketplace user interface, open the consumer access. The consumer access page's URL contains the unique identifier.
For example, in the URL https://{{CDMP_URL}}/access/e254491f-5795-49bd-be0b-385eb11d9d5a?dtn=Access~2e85, the unique identifier is e254491f-5795-49bd-be0b-385eb11d9d5a.
Ensure that the consumer access that you specify is in the AVAILABLE state.
Method
PATCH
For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the body of the API payload:
Parameter
Description
comment
Optional. Enter a comment about the action taken.

Example request

The following example shows how you can use an API to submit a withdrawal request for a consumer access:
Request query
https://{{CDMP_URL}}/api/v2/consumer-accesses/794a215f-5479-4b55-8e1b-a4866ec9fe82/request-withdrawal
Request body
{
"comment": "Requesting withdrawal as user has completed project and no longer requires access"
}

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.
If you see the following response code, it means that a request to withdraw the consumer access is successfully submitted:
204 OK code

Withdraw consumer accesses

Use a REST API to withdraw a Data User's access to a data collection.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v2/consumer-accesses/<consumerAccessId>/withdraw
<consumerAccessId>: Required. Enter the system-generated identifier of the consumer access that you want to withdraw.
For more information about how you can use an API to get the system-generated unique identifier of a consumer access, see Retrieve all consumer accesses.
To get the system-generated unique identifier of a consumer access from the Data Marketplace user interface, open the consumer access. The consumer access page's URL contains the unique identifier.
For example, in the URL https://{{CDMP_URL}}/access/e254491f-5795-49bd-be0b-385eb11d9d5a?dtn=Access~2e85, the unique identifier is e254491f-5795-49bd-be0b-385eb11d9d5a.
Ensure that the consumer access that you specify is in the AVAILABLE or PENDING_WITHDRAW state.
Method
PATCH
For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the body of the API payload:
Parameter
Description
comment
Optional. Enter a comment about the action taken.

Example request

The following example shows how you can use an API to withdraw a consumer access:
Request query
https://{{CDMP_URL}}/api/v2/consumer-accesses/794a215f-5479-4b55-8e1b-a4866ec9fe82/withdraw
Request body
{
"comment": "Revoking the access as user has completed project and no longer requires access"
}

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.
If you see the following response code, it means that the consumer access is successfully withdrawn:
204 OK code

Cancel consumer access withdrawals

Use a REST API to cancel a withdrawal request that is submitted for a consumer access.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v2/consumer-accesses/<consumerAccessId>/cancel-withdrawal
<consumerAccessId>: Required. Enter the system-generated identifier of the consumer access for which you want to cancel the withdrawal request.
For more information about how you can use an API to get the system-generated unique identifier of a consumer access, see Retrieve all consumer accesses.
To get the system-generated unique identifier of a consumer access from the Data Marketplace user interface, open the consumer access. The consumer access page's URL contains the unique identifier.
For example, in the URL https://{{CDMP_URL}}/access/e254491f-5795-49bd-be0b-385eb11d9d5a?dtn=Access~2e85, the unique identifier is e254491f-5795-49bd-be0b-385eb11d9d5a.
Ensure that the consumer access that you specify is in the PENDING_WITHDRAW state.
Method
PATCH
For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the body of the API payload:
Parameter
Description
comment
Optional. Enter a comment about the action taken.

Example request

The following example shows how you can use an API to cancel a withdrawal request that is submitted for a consumer access:
Request query
https://{{CDMP_URL}}/api/v2/consumer-accesses/794a215f-5479-4b55-8e1b-a4866ec9fe82/cancel-withdrawal
Request body
{
"comment": "Withdrawal cancelled - access still needed for ongoing project deliverables"
}

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.
If you see the following response code, it means that the consumer access withdrawal request is successfully cancelled:
204 OK code

Delete consumer accesses

Use a REST API to delete a withdrawn consumer access in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v2/consumer-accesses/<consumerAccessId>
<consumerAccessId>: Required. Enter the system-generated identifier of the consumer access that you want to delete.
For more information about how you can use an API to get the system-generated unique identifier of a consumer access, see Retrieve all consumer accesses.
To get the system-generated unique identifier of a consumer access from the Data Marketplace user interface, open the consumer access. The consumer access page's URL contains the unique identifier.
For example, in the URL https://{{CDMP_URL}}/access/e254491f-5795-49bd-be0b-385eb11d9d5a?dtn=Access~2e85, the unique identifier is e254491f-5795-49bd-be0b-385eb11d9d5a.
Method
DELETE
To invoke this API, ensure that your user profile is assigned the Data Marketplace Administrator role.
Alternatively, ensure that your user profile is assigned a role for which the following privileges and permissions are enabled:
For more information about how you can call an API, see Authenticate using JWT.

Request

Note: The API has no payload.

Example request

The following example shows how you can use an API to delete a consumer access:
https://{{CDMP_URL}}/api/v2/consumer-accesses/67417f72-e5ab-44f0-add9-a1e412c1ce13

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.
If you see the following response code, it means that the consumer access is successfully deleted:
204 OK code