Este método deja de estar disponible el 13 de octubre de 2026. Consulte la sección "Autenticación de API con OAuth2".

Autenticación de API con OAuth

¿Qué es?

OAuth 1.0a define un protocolo que permite a los usuarios de aplicaciones autorizar a aplicaciones que consuman sus APIs sin necesidad de que las contraseñas viajen en las peticiones.

• Documentación relacionada

Implementación

La implementación concreta que se utiliza es autenticación en un sólo paso, por lo que no es necesaria la obtención de claves adicionales (request_token o access_token), se puede seguir una explicación aquí:

• https://github.com/Kong/mashape-oauth/blob/master/FLOWS.md#oauth-10a-one-legged

Pruebas

En la consola de pruebas: https://apipre.cnmc.gob.es/. Se pueden ver todos los parámetros, puesto que utiliza autenticación OAuth.

¿Cómo autenticar solicitudes al API de la sede electrónica con el protocolo OAuth?

Guía detallada

Intentamos acceder al recurso securizado:

https://api.cnmc.gob.es/test/v1/echoseguro?m=Estoesunaprueba

1. El responsable de la aplicación cliente ha debido solicitar previamente, a través de la sede electrónica, sus credenciales o datos de autorización, por ejemplo: customerKey=dpf43f3p2l4k3l03 customerSecret=kd94hf93k423kf44
2. El cliente también no necesita ejecutar el flujo OAuth y debe usar: access token = null y token secret = null
3. Para firmar la petición, el cliente debe usar el algoritmo HMAC-SHA1
4. Y este genera la siguiente: nonce string kllo9940pd9333jh y este timestamp 1191242096

5. Los parámetros a enviar, incluyendo los utilizados por el propio servicio, quedan de la siguiente manera:

   Name="Value",
   oauth_consumer_key="dpf43f3p2l4k3l03",
   oauth_token="vacío",
   oauth_nonce="kllo9940pd9333jh",
   oauth_timestamp="1191242096",
   oauth_signature_method="HMAC-SHA1",
   oauth_version="1.0",
   m="Estoesunaprueba"

   Los parámetros OAuth se pueden enviar, esto es para la generación de la firma, como un authentication header (http://tools.ietf.org/html/rfc5849#section-3.5.1).

6. Estos parámetros se transforman siguiendo el RFC de OAuth (http://tools.ietf.org/html/rfc5849#section-3.5) siguiendo los siguientes pasos:
   1. Codificación de los mismos en UTF-8.

   2. Codificar los parámetros siguiendo URL-Encoding (http://en.wikipedia.org/wiki/Percent-encoding http://tools.ietf.org/html/rfc5849#section-3.6).

      Se ordenan basados en su codificación por URL-Encoding

      Name="Value",
      m="Estoesunaprueba",
      oauth_consumer_key="dpf43f3p2l4k3l03",
      oauth_nonce="kllo9940pd9333jh",
      oauth_signature_method="HMAC-SHA1",
      oauth_timestamp="1191242096",
      oauth_token="nnch734d00sl2jdk",
      oauth_version="1.0"

7. Una vez transformados se concatenan en una QueryString:

   m=Estoesunaprueba&oauth_consumer_key=dpf43f3p2l4k3l03&oauth_nonce=kllo9940pd9333jh&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1191242096&oauth_token=nnch734d00sl2jdk&oauth_version=1.0

8. Se normaliza la URL de la petición utilizando la especificación: http://tools.ietf.org/html/rfc5849#section-3.4.1.2 Ej.:
   • Full URL: https://api.cnmc.gob.es/test/v1/echoseguro
   • Normalized URL: https://api.cnmc.gob.es/test/v1/echoseguro

9. Para crear la "Signature Base String" se concatenan todas estas partes precedidas del método HTTP solicitado, que es una parte muy importante en los servicios REST:

   GET&http%3A%2F%2Fapi.sede.cnmc.gob.es%2Ftest%2Fecho&m%3DEstoesunaprueba%26oauth_consumer_key%3Ddpf43f3p2l4k3l03%26oauth_nonce%3Dkllo9940pd9333jh%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1191242096%26oauth_token%3Dnnch734d00sl2jdk%26oauth_version%3D1.0

10. Para calcular la firma HMAC-SHA1 usamos dos claves: client secret y token secret para el key del algoritmo HMAC-SHA1. Cada clave se codifica con: UTF8-encoded, URL-encoded y se concatena en una única cadena usando '&' como separador, aunque estén vacíos (ver seccion 3.4.2).

    kd94hf93k423kf44&pfkkdhi9sl3r4s00

11. Con la "Signature Base String", el texto HMAC-SHA1 concatenamos las claves, el cliente deberá generar la firma (RFC seccion 3.4.2). El algoritmo HMAC-SHA1 genera una cadena de bytes. Debe estar codificada base64-encoded con '=' para asegurar el "padding" (ver RFC 2045 seccion 6.8):

    tR3+Ty81lMeYAr/Fid0kMTYa/WM=

12. La firma calculada es entonces añadida a la petición usando el parámetro 'oauth_signature'. Una vez esta firma haya sido verificada por el servidor ya no se debe incluir en el flujo de firma y no es parte de "Signature Base String". Cuando se incluya en la cabecera HTTP debe estar codificada del mismo modo que se transmiten el resto de parámetros.

    Name="Value",
    oauth_signature="tR3+Ty81lMeYAr/Fid0kMTYa/WM="
    

13. Aunque OAuth no especifica directamente cómo se deben incluir estos parámetros en la petición, al definirlos en la firma para su verificación por el "Service Provider" implícitamente indica cuáles deben incluirse en la petición.

    Los parámetros OAuth pueden incluirse en uno de estos lugares:

    1. URL query (ver RFC 3986 seccion 3),
    2. OAuth 'Authorization' header (ver seccion 3.5.1),
    3. En un single-part 'application/x-www-form-urlencoded' POST body (como se define en HTML4).

    Los parámetros firmados non-OAuth pueden incluirse de alguna de estas formas:

    1. Como un elemento de la URL query.
    2. En un single-part 'application/x-www-form-urlencoded' POST body.

    Se recomienda que cuando sea posible los parámetros OAuth se incluyan en OAuth 'Authorization' header y no se incluyan más parámetros en el header.

Usando URL query para los parámetros non-OAuth y OAuth 'Authorization' header para OAuth la petición OAuth-signed HTTP queda así:

GET /test/echo?m=Estoesunaprueba HTTP/1.1 Host: http://api.cnmc.gob.es:80/test/v1/echoseguro Authorization: OAuth realm="http://api.cnmc.gob.es/test/v1/echoseguro", oauth_consumer_key="dpf43f3p2l4k3l03", oauth_token="nnch734d00sl2jdk", oauth_nonce="kllo9940pd9333jh", oauth_timestamp="1191242096", oauth_signature_method="HMAC-SHA1", oauth_version="1.0", oauth_signature="tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D"

Documentación Relacionada

• http://tools.ietf.org/html/rfc5849
• https://github.com/Kong/mashape-oauth/blob/master/FLOWS.md
• http://oauth.net/documentation/
• http://oauth.net/core/1.0a/
• http://hueniverse.com/oauth/
• http://hueniverse.com/oauth/guide/terminology/
• http://hueniverse.com/2007/10/04/beginners-guide-to-oauth-part-i-overview/
• 2-Legged http://tools.ietf.org/pdf/draft-ietf-oauth-v2-http-mac-01.pdf

Cómo obtener el token

El token se pide al servicio de autorización de la CNMC con el flujo client credentials de OAuth 2.0:

• Método: POST.
• Cuerpo (application/x-www-form-urlencoded): grant_type=client_credentials y, opcionalmente, scope=read.
• Autenticación: cabecera Authorization: Basic con ConsumerKey:ConsumerSecret codificado en Base64. Solo se admite esta forma: no envíe la clave ni el secreto como parámetros del cuerpo.

Ejemplo con curl (sustituya MI_CONSUMER_KEY y MI_CONSUMER_SECRET por los suyos):

curl -X POST "https://apipre.cnmc.gob.es/oauth2/token" \
  -u "MI_CONSUMER_KEY:MI_CONSUMER_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=read"

Respuesta (ejemplo):

{
  "access_token": "eyJraWQiOi...",
  "scope": "read",
  "token_type": "Bearer",
  "expires_in": 299
}

Duración del token y qué hacer cuando caduca

• El token dura 5 minutos (expires_in: 299 segundos).
• No hay refresh token: cuando caduque, pida uno nuevo exactamente igual que el primero.
• Reutilice el mismo token en todas las peticiones mientras esté vigente; no es necesario pedir uno por cada llamada. Una práctica sencilla: guarde la hora a la que lo obtuvo y pida otro cuando falten unos segundos para que caduque.
• Si una petición responde 401 (token caducado o no válido), pida un token nuevo y repita la petición una vez.
• En las subidas largas por trozos, compruebe la vigencia del token antes de enviar cada trozo.

Cómo llamar a la API con el token

Añada a cada petición la cabecera:

Authorization: Bearer <access_token>

Ejemplo (comprobar que la autenticación funciona y ver los datos de su credencial):

TOKEN="eyJraWQiOi..."   # el access_token obtenido en el paso anterior
curl -H "Authorization: Bearer $TOKEN" \
  "https://apipre.cnmc.gob.es/api-oauth2/test/perfil"

La respuesta incluye el NIF de la empresa, el NIF del contacto, el procedimiento y los roles de la credencial.

Equivalencias: si hoy usa OAuth 1.0, qué debe usar con OAuth 2.0

Los parámetros, cuerpos y respuestas de cada servicio son los mismos que en OAuth 1.0, salvo lo indicado en "Diferencias a tener en cuenta". Las rutas son relativas a https://api.cnmc.gob.es (producción) o https://apipre.cnmc.gob.es (preproducción). Fíjese en que en carga y descarga desaparece el /v1 de la ruta.

Carga de ficheros

Descarga de ficheros

Pruebas

Consultas de sistemas verticales (SIPS)

Se mantiene toda la ruta y solo se añade /api-oauth2 delante:

Ejemplo:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.cnmc.gob.es/api-oauth2/verticales/v1/SIPS/consulta/v1/SIPS2026_CONSUMOS_ELECTRICIDAD.csv?cups=ES0000000000000000XX"

(El valor de cups es ilustrativo. La extensión del tipo de fichero, .csv, .json…, es obligatoria, como en OAuth 1.0.)

Servicios públicos

Los servicios de consulta pública (/catalogo/v1/..., /maestras/v1/..., /anunciospublicos/v1/...) no cambian.

Servicios de seguridad (/seguridad/v1 y /seguridad/v2)

Son los servicios con los que su aplicación consulta en qué procedimientos está autorizada la credencial o un presentador:

Versión OAuth 2.0: disponible en preproducción y producción. Se añade /api-oauth2 delante de la ruta actual, con el token en la cabecera Authorization: Bearer:

• /api-oauth2/seguridad/v1/procedimientosAutorizados
• /api-oauth2/seguridad/v1/procedimientosAutorizados/{nifPresentador}
• /api-oauth2/seguridad/v1/autorizadoEnProcedimiento?nif=...&procedimiento=...
• /api-oauth2/seguridad/v1/procedimientos/permiso/{permiso}
• /api-oauth2/seguridad/v2/procedimientos/permiso/{permiso}
• /api-oauth2/seguridad/v2/procedimientos/permiso/{permiso}/roles
• /api-oauth2/seguridad/v2/procedimiento/{idProcedimiento}/permiso/{permiso}

Tienen los mismos parámetros y respuestas que las actuales, con una diferencia: las consultas por NIF (procedimientosAutorizados/{nifPresentador} y autorizadoEnProcedimiento) solo responden para el NIF de la propia credencial o el de un contacto vigente de su empresa; para cualquier otro NIF devuelven un error 403.

Diferencias a tener en cuenta

1. Ruta. Todas las rutas OAuth 2.0 empiezan por /api-oauth2/. En carga y descarga desaparece el /v1; en verticales se mantiene.

2. Fecha de efecto (fechaEfecto) en cargar_fichero_completo. Antes del 13 de octubre de 2026, con OAuth 2.0 se admitirán dos formatos:

   • AAAA-MM-DD (por ejemplo, 2026-10-01), opcionalmente con hora AAAA-MM-DD HH:mm o AAAA-MM-DD HH:mm:ss.
   • MM/DD/AAAA, con el mes primero, como en OAuth 1.0 (por ejemplo, 10/01/2026 es el 1 de octubre de 2026).

   Siempre con dos cifras para el mes y el día y cuatro para el año. Cualquier otro formato, o una fecha que no existe (por ejemplo 02/30/2026 o 31/12/2026), se rechaza con un error 400. Con OAuth 1.0 algunas de esas fechas se aceptaban y se convertían en otra fecha distinta; con OAuth 2.0 ya no. Revise el formato que envía su aplicación.

3. Justificante de la carga. Descargue el justificante con /api-oauth2/carga/obtener_justificante/{uuidCarga}. Antes del 13 de octubre de 2026, el enlace que devuelve consultar_estado_carga vendrá ya con esa ruta.
4. Enlaces de descarga de ficheros. Úselos tal cual los devuelve la consulta; no hace falta enviar el token.
5. /api-oauth2/test/perfil frente a /test/v1/nif. perfil devuelve nifEmpresa, nifContacto, procedimiento, roles y oauthConsumerKey; ya no devuelve la lista de NIF de empresas (empresa) que daba /test/v1/nif.
6. Envío de ficheros. Las operaciones que suben ficheros (cargar_fichero_completo, subir_fichero_completo, subir_chunk_fichero) deben enviarse como multipart/form-data. Los nombres de los campos son los mismos que en OAuth 1.0.

Errores habituales

Las respuestas de error de los servicios (400, 403) llegan en JSON (application/api-problem+json), con un título y una descripción del problema. Los 401 de un token caducado o no válido llegan sin cuerpo, con la cabecera WWW-Authenticate: Bearer ....

Registro de Alias

En este enlace están los ejemplos de los tipos de ficheros disponibles para la descarga.