Certificates API

The Certificates service provides methods for managing X.509 certificates, which are used for cryptographic operations and identity verification in the Cross-Media Measurement system.

Resource

Certificate

Resource representing an X.509 certificate. Resource Patterns:

dataProviders/{data_provider}/certificates/{certificate}
duchies/{duchy}/certificates/{certificate}
measurementConsumers/{measurement_consumer}/certificates/{certificate}
modelProviders/{model_provider}/certificates/{certificate}

name

string

required

Resource name.The resource ID alias “preferred” may be used in place of the certificate ID to refer to the preferred Certificate.Examples:

measurementConsumers/mc-123/certificates/cert-456
dataProviders/dp-789/certificates/preferred

x509_der

bytes

required

X.509 certificate in DER format. Required. Immutable.

revocation_state

RevocationState

RFC 5280 revocation state of the certificate reported by an API caller.If specified, it means that the certificate is not currently valid. Output-only.

This is not guaranteed to reflect the actual revocation state determined by the issuing certificate authority.

Possible values:

REVOCATION_STATE_UNSPECIFIED - Default value
HOLD - Certificate is on hold and therefore invalid, possibly temporarily
REVOKED - Certificate has been revoked (terminal state)

subject_key_identifier

bytes

X.509 v3 subject key identifier. Output-only.

Methods

GetCertificate

Returns the Certificate with the specified resource name.

name

string

required

Resource name of the Certificate.Format: {parent}/certificates/{certificate}The certificate ID can be “preferred” to get the preferred certificate.

response

Certificate

The Certificate resource.

Example Request

message GetCertificateRequest {
  string name = 1;  // "measurementConsumers/mc-123/certificates/cert-456"
                   // or "dataProviders/dp-789/certificates/preferred"
}

Error Conditions

NOT_FOUND - Certificate not found
INVALID_ARGUMENT - Invalid resource name format

CreateCertificate

Creates (adds) a Certificate.

parent

string

required

Name of the parent resource.Can be one of:

dataProviders/{data_provider}
duchies/{duchy}
measurementConsumers/{measurement_consumer}
modelProviders/{model_provider}

certificate

Certificate

required

The Certificate to create.The name field will be ignored, and the system will assign an ID.

Show Certificate fields

response

Certificate

The created Certificate resource.

Example Request

message CreateCertificateRequest {
  string parent = 1;        // "measurementConsumers/mc-123"
  Certificate certificate = 2;
}

message Certificate {
  bytes x509_der = 2;  // DER-encoded X.509 certificate bytes
}

Example Response

message Certificate {
  string name = 1;                      // "measurementConsumers/mc-123/certificates/cert-456"
  bytes x509_der = 2;                   // DER-encoded certificate
  bytes subject_key_identifier = 4;     // Extracted from certificate
}

Error Conditions

INVALID_ARGUMENT - Invalid certificate data or malformed X.509
NOT_FOUND - Parent resource not found
PERMISSION_DENIED - Caller lacks permission to create certificates for parent

ListCertificates

Lists Certificate resources.

parent

string

required

Name of the parent resource.Format: One of the parent resource patterns listed above.

page_size

int32

The maximum number of resources to return.The service may return fewer than this value. If unspecified, at most 50 resources will be returned. The maximum value is 1000; values above the maximum will be coerced to the maximum.

page_token

string

A page token, received from a previous call.When paginating, all other request parameters must match those of the call that provided the page token.

filter

Filter

Filter criteria for this request.Repeated fields are treated as logical ORs, and multiple fields specified as logical ANDs.

Show Filter fields

certificates

repeated Certificate

List of Certificate resources.

next_page_token

string

A token, which can be sent as page_token to retrieve the next page.If this field is omitted, there are no subsequent pages.

Example Request

message ListCertificatesRequest {
  string parent = 1;      // "measurementConsumers/mc-123"
  int32 page_size = 2;    // 50
  string page_token = 3;  // "" (empty for first page)
  
  message Filter {
    repeated bytes subject_key_identifiers = 1;
  }
  Filter filter = 4;
}

Example Response

message ListCertificatesResponse {
  repeated Certificate certificates = 1;  // Array of certificates
  string next_page_token = 2;             // Token for next page, or empty
}

Filtering by Subject Key Identifier

ListCertificatesRequest {
  parent: "measurementConsumers/mc-123"
  filter: {
    subject_key_identifiers: [
      "\x01\x02\x03...",  // First subject key ID
      "\x04\x05\x06..."   // Second subject key ID (OR)
    ]
  }
}

RevokeCertificate

Revokes a Certificate by setting its revocation state.

name

string

required

Resource name of the Certificate.Format: {parent}/certificates/{certificate}

revocation_state

RevocationState

required

Revocation state to set.Valid values:

HOLD - Place certificate on hold (temporarily invalid)
REVOKED - Permanently revoke the certificate

response

Certificate

The updated Certificate resource with revocation state set.

Example Request

message RevokeCertificateRequest {
  string name = 1;                              // "measurementConsumers/mc-123/certificates/cert-456"
  Certificate.RevocationState revocation_state = 2;  // HOLD or REVOKED
}

Error Conditions

NOT_FOUND - Certificate not found
INVALID_ARGUMENT - Invalid revocation state
PERMISSION_DENIED - Caller lacks permission to revoke the certificate
FAILED_PRECONDITION - Certificate already in terminal revocation state

ReleaseCertificateHold

Releases a Certificate with a revocation state of HOLD by clearing its revocation state.

name

string

required

Resource name of the Certificate.Format: {parent}/certificates/{certificate}

response

Certificate

The updated Certificate resource with revocation state cleared.

Example Request

message ReleaseCertificateHoldRequest {
  string name = 1;  // "measurementConsumers/mc-123/certificates/cert-456"
}

Error Conditions

NOT_FOUND - Certificate not found
FAILED_PRECONDITION - Certificate is not in HOLD state
PERMISSION_DENIED - Caller lacks permission to release the certificate

Usage Patterns

Creating and Managing Certificates

Create a certificate:

CreateCertificateRequest {
  parent: "measurementConsumers/mc-123"
  certificate: {
    x509_der: <DER-encoded certificate bytes>
  }
}

Get the preferred certificate:

GetCertificateRequest {
  name: "measurementConsumers/mc-123/certificates/preferred"
}

List all certificates for a parent:

ListCertificatesRequest {
  parent: "measurementConsumers/mc-123"
  page_size: 50
}

Certificate Revocation Workflow

Temporarily suspend a certificate:

RevokeCertificateRequest {
  name: "measurementConsumers/mc-123/certificates/cert-456"
  revocation_state: HOLD
}

Release the hold if issue resolved:

ReleaseCertificateHoldRequest {
  name: "measurementConsumers/mc-123/certificates/cert-456"
}

Permanently revoke if compromised:

RevokeCertificateRequest {
  name: "measurementConsumers/mc-123/certificates/cert-456"
  revocation_state: REVOKED
}

Once a certificate is in REVOKED state, it cannot be released. This is a terminal state.

Filtering Certificates

Find certificates by subject key identifier:

ListCertificatesRequest {
  parent: "dataProviders/dp-789"
  filter: {
    subject_key_identifiers: [<bytes>]
  }
}

Revocation States

Certificates can have the following revocation states:

State	Description	Reversible
`REVOCATION_STATE_UNSPECIFIED`	No revocation (valid)	N/A
`HOLD`	Temporarily suspended	Yes, via `ReleaseCertificateHold`
`REVOKED`	Permanently revoked	No (terminal state)

The revocation state is reported by API callers and may not reflect the actual state determined by the certificate authority.

Best Practices

Use the “preferred” alias to always get the current active certificate
Store certificates in DER format before uploading
Use HOLD state for temporary suspensions during investigation
Use REVOKED state only when permanently retiring a certificate
Monitor certificate expiration dates outside the API
Maintain multiple certificates and rotate them before expiration

Overview

Identity & Access

Measurement Resources

Event Management

Model Management

Panel Matching

Populations

Resource

Certificate

Methods

GetCertificate

Example Request

Error Conditions

CreateCertificate

Example Request

Example Response

Error Conditions

ListCertificates

Example Request

Example Response

Filtering by Subject Key Identifier

RevokeCertificate

Example Request

Error Conditions

ReleaseCertificateHold

Example Request

Error Conditions

Usage Patterns

Creating and Managing Certificates

Certificate Revocation Workflow

Filtering Certificates

Revocation States

Best Practices

Build docs developers (and LLMs) love

Overview

Identity & Access

Measurement Resources

Event Management

Model Management

Panel Matching

Populations

​Resource

​Certificate

​Methods

​GetCertificate

​Example Request

​Error Conditions

​CreateCertificate

​Example Request

​Example Response

​Error Conditions

​ListCertificates

​Example Request

​Example Response

​Filtering by Subject Key Identifier

​RevokeCertificate

​Example Request

​Error Conditions

​ReleaseCertificateHold

​Example Request

​Error Conditions

​Usage Patterns

​Creating and Managing Certificates

​Certificate Revocation Workflow

​Filtering Certificates

​Revocation States

​Best Practices

Build docs developers (and LLMs) love

Resource

Certificate

Methods

GetCertificate

Example Request

Error Conditions

CreateCertificate

Example Request

Example Response

Error Conditions

ListCertificates

Example Request

Example Response

Filtering by Subject Key Identifier

RevokeCertificate

Example Request

Error Conditions

ReleaseCertificateHold

Example Request

Error Conditions

Usage Patterns

Creating and Managing Certificates

Certificate Revocation Workflow

Filtering Certificates

Revocation States

Best Practices