Service DIDs

Un Service DID es una identidad descentralizada para un sistema de una organización: una API, un proceso automático, un pipeline o un agente de IA. No representa a la organización en sí, sino a algo que actúa en su nombre.

Cada Service DID depende de un did:isbe organizativo ya registrado en ISBE, al que llamamos DID paraguas. El paraguas es quien lo crea, quien lo puede modificar y quien responde por él.

¿Para qué sirve?

Una organización registrada en ISBE tiene su DID y su clave de control. Si sus sistemas usaran esa misma clave para firmar, cualquier fallo en uno de ellos comprometería la identidad de toda la organización. Los Service DIDs resuelven eso:

• Cada sistema tiene su propia clave. La clave de la organización no sale nunca de donde está guardada.
• Si la clave de un servicio se ve comprometida, se rota o se desactiva ese servicio, sin tocar el DID de la organización ni el resto de sus servicios.
• Se sabe quién firma. Una firma hecha por un servicio se puede atribuir a ese servicio y a la organización que lo controla.
• Cada servicio puede publicar información sobre sí mismo (endpoints, versión, contacto…) en su DID Document, que cualquiera puede consultar.

Algunos ejemplos:

Sistema	Service DID
Una API de facturación electrónica	Firma las facturas que emite
Un proceso nocturno de conciliación	Firma los informes que genera
Un agente de IA que tramita solicitudes	Se identifica ante otros sistemas cuando actúa
Un emisor de credenciales	Publica su endpoint OpenID4VCI en el DID Document

Formato del identificador

did:isbe:svc:<modelDeploy>:<identificador del paraguas>:<n>

• svc indica que es un Service DID, no un DID organizativo.
• <modelDeploy> es el entorno: uc-pre en pre-producción y uc en producción, igual que en el DID paraguas.
• <identificador del paraguas> es la parte final del DID organizativo que lo controla.
• <n> es un contador propio de cada paraguas: su primer servicio es el 1, el segundo el 2, y así sucesivamente.

Por ejemplo, el tercer servicio de la organización did:isbe:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk es:

did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3

Como el identificador del paraguas forma parte del Service DID, basta con leerlo para saber qué organización lo controla.

Cómo funciona

La cadena de confianza es la misma que la del DID organizativo: la organización se identifica al registrarse en ISBE, y sus servicios heredan esa confianza a través del paraguas. No hay una gobernanza nueva.

El paraguas lo controla todo

• Solo el paraguas puede crear, modificar o desactivar sus Service DIDs. Todas esas operaciones las tiene que firmar una cuenta con capacidad de invocación activa en el DID paraguas: la misma con la que gestionas tu DID organizativo.
• La clave de un servicio no puede modificar su propio Service DID. Sirve para que el servicio firme lo suyo, no para gestionar su identidad.
• Si un paraguas tiene varios controladores, cualquiera de ellos puede gestionar sus servicios.

La API no guarda claves

Igual que la DID Registry API, la Service DID Registry API no custodia claves privadas. Cada operación de escritura devuelve una transacción sin firmar. La firmas en tu equipo con el CLI isbe-identity-did-gen y la envías a la API para que la publique en la red. Tu clave privada nunca sale de tu equipo.

Los Service DIDs se guardan en el mismo contrato que los DIDs organizativos: el Diamond 0x00000000000000000000000000000000000015BE.

La clave del servicio

Cada Service DID tiene una clave de firma secp256k1. La generas con did-gen keys, igual que la de tu DID organizativo, pero es una clave distinta.

¿Se puede usar esta clave para un servicio?
Una clave nueva, generada para el servicio	✅ Sí
La misma clave que otro servicio del mismo paraguas	✅ Sí: los servicios de un mismo paraguas pueden compartir clave
La clave de cualquier DID organizativo, incluido el propio paraguas	❌ No
La clave de un servicio de otro paraguas	❌ No

Una clave queda ligada para siempre al paraguas del primer servicio que la usó, aunque ese servicio la rote después o se desactive. Así, cada firma se puede atribuir sin ambigüedad a una sola organización.

Compartir clave entre servicios

Compartir clave es útil cuando varios servicios corren en la misma máquina. Ten en cuenta que, si comparten clave, una firma te dice qué organización la hizo, pero no cuál de esos servicios. Si necesitas distinguirlos, dale a cada uno su propia clave.

Campos libres

Además de los datos mínimos, al registrar un Service DID puedes añadir los campos que quieras: nombre del servicio, descripción, datos de la organización, contacto, versión, endpoints… Se guardan en la cadena y aparecen en el DID Document del servicio.

Un caso típico es la propiedad service del estándar W3C DID Core (§5.4), que publica los endpoints del servicio:

"service": [
  {
    "id": "#api",
    "type": "InvoicingAPI",
    "serviceEndpoint": "https://api.facturacion.ejemplo.es/v2"
  }
]

Reglas de los campos libres:

• Tamaño máximo: 4096 bytes en total.
• No puedes usar los campos que genera el propio registro: @context, id, controller, verificationMethod, authentication, assertionMethod, capabilityInvocation, capabilityDelegation, keyAgreement, deactivated y reason.
• Al modificarlos se sustituyen enteros: los campos nuevos reemplazan a todos los anteriores, no se mezclan.

Los campos libres son públicos

Todo lo que pongas en los campos libres queda en la blockchain, a la vista de cualquiera, y su historial no se puede borrar. No incluyas datos personales, secretos ni información confidencial.

El DID Document de un Service DID

Al resolver un Service DID obtienes un DID Document W3C. Por ejemplo:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/secp256k1recovery-2020/v2"
  ],
  "id": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
  "controller": ["did:isbe:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk"],
  "verificationMethod": [
    {
      "id": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3#key-1",
      "type": "EcdsaSecp256k1RecoveryMethod2020",
      "controller": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
      "blockchainAccountId": "eip155:<chainId>:0x<dirección de la clave del servicio>"
    }
  ],
  "authentication": ["did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3#key-1"],
  "assertionMethod": ["did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3#key-1"],

  "name": "Servicio de Facturación Electrónica",
  "service": [
    {
      "id": "#api",
      "type": "InvoicingAPI",
      "serviceEndpoint": "https://api.facturacion.ejemplo.es/v2"
    }
  ]
}

• controller es el DID paraguas.
• verificationMethod contiene la clave del servicio, identificada por la dirección que se deriva de ella (blockchainAccountId).
• A continuación aparecen los campos libres del servicio, en este ejemplo name y service.

Cuándo deja de ser válido

Un Service DID está activo mientras no se cumpla ninguna de estas condiciones. Si se cumple alguna, al resolverlo el DID Document incluye "deactivated": true y un reason que indica el motivo:

reason	Qué ha pasado
deactivated	El paraguas lo ha desactivado. Es definitivo: no se puede reactivar.
expired	Ha pasado su fecha de caducidad (expiresAt). El paraguas puede ampliarla.
controller-inactive	El DID paraguas ya no tiene ninguna clave con capacidad de invocación activa. Todos sus servicios dejan de ser válidos a la vez.

Al registrar un servicio puedes fijar su caducidad o dejarla en 0, que significa que no caduca.

Siguientes pasos

• Registrar un Service DID — Procedimiento paso a paso.
• Gestionar un Service DID — Cambiar sus campos libres, rotar la clave, cambiar la caducidad y desactivarlo.
• Entornos — URLs de la Service DID Registry API en cada entorno.