Services API
The services API manages service instances — the configurations that connect the Reference Implementation to its dependent services (verifiable credential services, storage services, and identity resolver services).
Each service instance records which adapter to use, the connection details (base URL, API key, etc.), and whether the instance is the primary for its service type. The configuration is encrypted at rest and sensitive fields (such as API keys) are masked in API responses.
For background on how services fit into the architecture, see Service Architecture.
The Reference Implementation includes a Swagger UI at /api-docs with full request/response schemas you can try directly from the browser. The endpoint descriptions below focus on behaviour and internal logic — refer to Swagger for exact payload shapes. All endpoints require authentication — see Authentication for how to obtain a Bearer token.
Concepts
Service Types and Adapter Types
Every service instance has a service type (what category of service it provides) and an adapter type (which specific implementation it uses). The supported service types and their available adapters are documented on the Service Architecture page.
Each adapter type has its own configuration schema. When creating or updating a service instance, the config object is validated against the adapter's schema before being encrypted and stored. See the adapter pages within each service for the configuration fields each adapter requires:
System Services vs Tenant Services
Service instances exist at two levels — system services (created during startup, owned by the system tenant, read-only defaults visible to all tenants) and tenant services (created through this API, scoped exclusively to the creating tenant). See System Services vs Tenant Services for details.
Primary Instances
Each tenant can designate one service instance per service type as the primary. The primary instance is used by default when other operations (such as DID creation or credential issuance) need a service of that type but no specific instance is specified.
When a service instance is created or updated with isPrimary: true, any existing primary for the same service type within the tenant is automatically demoted to isPrimary: false.
Configuration Encryption
Service configurations contain sensitive data (API keys, credentials). The config object is encrypted at rest and sensitive fields are masked in API responses.
Endpoints
Create a service instance
POST /api/v1/services
Registers a new service instance for the authenticated tenant. The config object is validated against the adapter's schema (see Service Types and Adapter Types above), encrypted, and stored.
List service instances
GET /api/v1/services
Returns service instances for the authenticated tenant, including system defaults. Results are paginated and can be filtered by service type and adapter type.
Get a service instance
GET /api/v1/services/{id}
Retrieves a specific service instance by its database ID. The tenant can access instances they own and system defaults.
Update a service instance
PATCH /api/v1/services/{id}
Updates one or more fields of a service instance owned by the tenant. System defaults cannot be updated.
When config is provided, the new fields are merged with the existing configuration (shallow merge), the merged result is validated against the adapter's schema, and then encrypted before storage. This means you can update individual config fields without re-sending the entire config object.
Delete a service instance
DELETE /api/v1/services/{id}
Permanently deletes a service instance owned by the tenant. System defaults cannot be deleted.
If the instance is referenced by other records (DIDs, registrars, or identifier schemes), the request is rejected with a 409 Conflict unless force=true is set. When forced, the foreign keys on referencing records are set to null.