Setup

We will setup a Credential Status service inside of a tenant. If you don't have a tenant yet, you can learn how to create one here.

Currently, status credentials can be stored and made available via five types of external services:

  1. AWS S3 Bucket
  2. Azure Blob Storage
  3. Google Cloud Storage
  4. S3-compatible Storage
  5. In-Memory

We support three ways to authenticate with each of these supported services:

  1. Managed Identity Recommended for AWS and Azure.
  2. Config Recommended for GCP and S3-compatible storage.
  3. Registry Recommended for quick testing and local development.

Its also important to note how you can configure the size of your status list.

via Managed Identity

The Credential Status service can be configured to use a managed identity for authentication. This is useful when you want to use a service principal for authentication. This is the recommended way to configure the Credential Status service.

It is currently only supported for AWS and Azure. For GCP and S3-compatible storage, we recommend you to use the configRef method below.


CURL

Endpoint: /v1/{target}/resource-api/services/create | API Reference

AWS
Azure
Google
S3-compatible
In-Memory

Configuration options vary based on the bucket's hosting environment and its access method.

AWS domain
CDN (custom domain)

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "credential-status",
  "config": {
    "registry": {
      "type": "aws",
      "bucketName": "bucket-name",
      "region": "region"
    }
  }
}'

Body

{
  "type": "credential-status",
  "config": {
    "registry": {
      "type": "aws",
      "bucketName": "bucket-name",
      "region": "region"
    }
  }
}

Body Parameters

  • type: credential-status - Specifies the type of service to create. In this case, it is credential-status.
  • config: object - Storage configurations for status credential service.
  • registry: object - Defines registry & access credentials for chosen registry.
    • type: aws - Indicates the type of registry, which is aws in this context.
    • bucketName: string - The name of the AWS S3 bucket.
    • region: string - The AWS region where the bucket is located.
    • endpointUrl: string - (Optional) The URL of the S3-compatible registry bucket, e.g. https://s3-mock.com.
  • bucketUrl: string - (Optional) The URL of the registry bucket custom domain, e.g. https://custom-domain.com.

via Config

Instead of sending storage credentials inline for every Credential Status service, you can define reusable storage profiles in waltid-enterprise-api/config/resource-access.conf and reference them via configRef when creating services through the Enterprise API.

The configuration file uses HOCON and defines a resourceAccess map, where each entry is a named storage profile:

resourceAccess = {
  # AWS S3 Example
  aws-s3-standard = {
    _type  = "AwsS3Access"
    id     = "s3-storage"
    region = "eu-north-1"
    bucket = { bucketName = "my-bucket" }
    credentials = {
      _type       = "AwsCredentials"
      accessKeyId = "abc"
      secretKey   = "xyz"
    }
  },

  # Azure Blob Storage Example
  azure-blob-storage = {
    _type  = "AzureBlobAccess"
    id     = "azure-storage"
    bucket = {
      bucketName = "documents"
      bucketUrl  = "https://example.blob.core.windows.net/"
    }
    credentials = {
      _type            = "AzureCredentials"
      connectionString = "DefaultEndpointsProtocol=https;AccountName=example;AccountKey=..."
    }
  },

  # Google Cloud Storage Example
  gcp-storage = {
    _type     = "GcpStorageAccess"
    id        = "gcp-storage-main"
    projectId = "my-project"
    bucket    = { bucketName = "gcp-bucket-main" }
    credentials = {
      _type = "GcpCredentials"
      serviceAccountKeyJson = {
        type                        = "service_account"
        project_id                  = "my-project"
        private_key_id              = "abc123..."
        private_key                 = "-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
"
        client_email                = "service-account@my-project.iam.gserviceaccount.com"
        client_id                   = "1234567890"
        auth_uri                    = "https://accounts.google.com/o/oauth2/auth"
        token_uri                   = "https://oauth2.googleapis.com/token"
        auth_provider_x509_cert_url = "https://www.googleapis.com/oauth2/v1/certs"
        client_x509_cert_url        = "https://www.googleapis.com/robot/v1/metadata/x509/service-account%40my-project.iam.gserviceaccount.com"
        universe_domain             = "googleapis.com"
      }
    }
}

When creating a credential-status service, you can now reference one of these profiles instead of providing the full storage configuration inline:

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "credential-status",
  "config": {
    "configRef": "aws-s3-standard"
  }
}'

Example Request Body

{
  "type": "credential-status",
  "config": {
    "configRef": "aws-s3-standard"
  }
}

At runtime, the Enterprise API resolves the configRef against resource-access.conf whenever the Credential Status service needs to read or write a status list. This allows centralized credential management and rotation without updating individual service records in the database.

via Registry

CURL

Endpoint: /v1/{target}/resource-api/services/create | API Reference

AWS
Azure
Google
S3-compatible
In-Memory

Configuration options vary based on the bucket's hosting environment and its access method.

AWS domain
CDN (custom domain)

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "credential-status",
  "config": {
    "registry": {
      "type": "aws",
      "bucketName": "bucket-name",
      "region": "region",
      "accessKeyId": "s3-access-key-id",
      "secretKey": "s3-secret-key"
    }
  }
}'

Body

{
  "type": "credential-status",
  "config": {
    "registry": {
      "type": "aws",
      "bucketName": "bucket-name",
      "region": "region",
      "accessKeyId": "s3-access-key-id",
      "secretKey": "s3-secret-key"
    }
  }
}

Body Parameters

  • type: credential-status - Specifies the type of service to create. In this case, it is credential-status.
  • config: object - Storage configurations for status credential service.
  • registry: object - Defines registry & access credentials for chosen registry.
    • type: aws - Indicates the type of registry, which is aws in this context.
    • bucketName: string - The name of the AWS S3 bucket.
    • region: string - The AWS region where the bucket is located.
    • accessKeyId: string - (Optional) The access key ID for accessing the AWS S3 bucket.
    • secretKey: string - (Optional) The secret access key for accessing the AWS S3 bucket.
    • endpointUrl: string - (Optional) The URL of the S3-compatible registry bucket, e.g. https://s3-mock.com.
  • bucketUrl: string - (Optional) The URL of the registry bucket custom domain, e.g. https://custom-domain.com.

    AWS access credentials are optional. If not provided, the default Credential Provider Chain will be executed, relying on AWS environment configuration (e.g. EC2 instance IAM role-provided credentials).

Capacity Configuration

You can configure capacity settings when creating a credential status service to enable monitoring and automatic rollover when status lists approach capacity.

CURL

Endpoint: POST /v1/{target}/resource-api/services/create | API Reference

Example Request
curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "credential-status",
  "config": {
    "registry": {
      "type": "in-memory"
    },
    "capacity": {
      "maxEntries": 32000,
      "warningThresholdPercent": 50,
      "criticalThresholdPercent": 80,
      "autoRollover": true,
      "rolloverSuffix": "-v"
    }
  }
}'

Path Parameters

  • orgID: String (required) - Your organization's Base URL. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.waltid.dev when using the sandbox environment.
  • target: String (required) - The target resource identifier specifying the organization and tenant. Format: {organizationID}.{tenantID}, e.g. waltid.tenant1

Header Parameters

  • Authorization: String (required) - Bearer token obtained from your Enterprise authentication. Format: Bearer {token}.

Body Parameters

  • type: String (required) - The service type to create. Must be "credential-status" for this service.
  • config: Object (required) - Service configuration object containing:
    • registry: Object (required) - Storage configuration for status credentials. See Registry Configuration for available options.
    • capacity: Object (optional) - Capacity monitoring and rollover configuration. Contains:
      • maxEntries: Integer (optional) - Maximum entries for this status list. Range: 1-32,000. Defaults to 32000.
      • warningThresholdPercent: Integer (optional) - Percentage at which WARNING status is triggered. Range: 1-99. Defaults to 80.
      • criticalThresholdPercent: Integer (optional) - Percentage at which CRITICAL status is triggered. Must be greater than warningThresholdPercent. Defaults to 95.
      • autoRollover: Boolean (optional) - Enable automatic creation of a new status list when the critical threshold is reached. Defaults to false.
      • rolloverSuffix: String (optional) - Suffix appended to versioned rollover status lists (e.g., config-v2, config-v3). Defaults to "-v".

Automatic Rollover

When autoRollover is enabled, the system automatically creates a new status list when the current one reaches the critical threshold:

  1. New entries continue to be created using the same base config ID
  2. The system automatically routes to the active status list version
  3. New status lists are named with the configured suffix (e.g., config-v2, config-v3)
  4. Existing entries remain in their original status lists

Automatic rollover requires the ES_CREDENTIAL_STATUS_CREATE_LIST permission in addition to ES_CREDENTIAL_STATUS_CREATE_STATUS_ENTRY.

Monitoring Capacity

Use the capacity endpoint to check status list usage:

GET /v1/{target}/credential-status-service-api/status-credential/capacity

See Manage Status Credentials for details on the response format and status values.

Last updated on June 15, 2026
OverviewManage