Restringe el acceso a la API con claves de API

Puedes usar las claves de API para restringir el acceso a métodos de API específicos o a todos los métodos en una API. En esta página, se describe cómo restringir el acceso a la API a los clientes que tienen una clave de API y, también, cómo crear una clave de API.

Si configuras un requisito de clave en tu API, se rechazan las solicitudes a la clase, la API o el método protegidos si no tienen una clave generada en tu proyecto o en otros proyectos que pertenezcan a desarrolladores a los que les hayas otorgado acceso para habilitar tu API. El proyecto en el que se creó la clave de API no se registra y no se agrega al encabezado de la solicitud. Sin embargo, puedes ver el proyecto de Google Cloud con el que está asociado un cliente en la página Servicios de Endpoints, como se describe en Filtro para un proyecto de consumidor específico.

Para obtener información sobre en qué proyecto de Google Cloud se debe crear una clave de API, consulta Compartir API protegidas por claves de API.

Restringe el acceso a todos los métodos de la API

Si deseas que se requiera una clave de API para todas las llamadas a Ia API, agrega apiKeyRequired = AnnotationBoolean.TRUE a tu anotación @Api. Por ejemplo:

@Api(
  name = "echo",
  version = "v1",
  apiKeyRequired = AnnotationBoolean.TRUE
  )
public class Echo {
//API class and methods...
}

Restringe el acceso a métodos de la API específicos

Si deseas que se requiera una clave de API para todas las llamadas hacia un método específico de la API, agrega apiKeyRequired = AnnotationBoolean.TRUE a tu anotación @ApiMethod. Por ejemplo:

@ApiMethod(name = "echo_api_key", path = "echo_api_key", apiKeyRequired = AnnotationBoolean.TRUE)
public Message echoApiKey(Message message, @Named("n") @Nullable Integer n) {
  return doEcho(message, n);
}

Si deseas que se requiera una clave de API para todas las llamadas hacia una clase específica de la API, agrega apiKeyRequired = AnnotationBoolean.TRUE a tu anotación @ApiClass.

Quitar la restricción de clave de API de un método

Para desactivar la validación de claves de API para una API o método de API, quita api_key_required=True (Python) o apiKeyRequired = AnnotationBoolean.TRUE (Java) de tu anotación o decorador de método o API. Luego, vuelve a compilarla y a implementarla.

Llamar a una API mediante una clave de API

Si una API o un método de API requiere una clave de API, proporciona la clave mediante un parámetro de consulta llamado key, como se muestra en este ejemplo con cURL:

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"message": "echo"}' \
    "${HOST}/_ah/api/echo/v1/echo_api_key?key=${API_KEY}"

En el ejemplo anterior, HOST y API_KEY son variables que contienen el nombre del host de tu API y la clave de API, respectivamente. Reemplaza echo por el nombre de tu API y v1 por la versión de tu API.

Comparte API protegidas por claves de API

Las claves de API están asociadas al proyecto de Google Cloud en el que se crearon. Si decidiste solicitar una clave de API para tu API, el proyecto de Google Cloud en el que se crea la clave de API depende de las respuestas a las siguientes preguntas:

  • ¿Necesitas distinguir entre los emisores de tu API de modo que puedas usar características de Endpoints, como las quotas?
  • ¿Todos los emisores de tu API tienen sus propios proyectos de Google Cloud?
  • ¿Necesitas configurar restricciones de clave de API diferentes?

Puedes usar el siguiente árbol de decisión como guía para decidir en qué proyecto de Google Cloud se creará la clave de API.

Árbol de decisión de clave de API

Otorga permisos para habilitar la API

Cuando necesites distinguir entre los emisores de tu API y cada emisor tiene su propio proyecto de Google Cloud, puedes otorgar a las principales permiso para habilitar la API en su propio proyecto de Google Cloud. De esta forma, los usuarios pueden crear su propia clave de API para usarla en tu API.

Por ejemplo, supongamos que tu equipo creó una API de uso interno para varios programas cliente de tu empresa y cada programa cliente tiene su propio proyecto de Google Cloud. Si necesitas distinguir entre los emisores de la API, se debe crear una clave de API para cada emisor en un proyecto de Google Cloud diferente. Puedes otorgar a tus compañeros de trabajo permiso para habilitar la API en el proyecto de Google Cloud con el que está asociado el programa cliente.

Para permitir que los usuarios creen sus propias claves de API, haz lo siguiente:

  1. En el proyecto de Google Cloud en el que está configurada tu API, otorga a cada usuario permiso para habilitar tu API.
  2. Informa a los usuarios que pueden habilitar la API en su propio proyecto de Google Cloud y crear una clave de API.

Crea un proyecto de Google Cloud por separado para cada emisor

Cuando necesites distinguir entre los emisores de tu API y no todos los emisores tengan proyectos de Google Cloud, puedes crear un proyecto de Google Cloud y una clave de API diferentes para cada emisor. Antes de crear los proyectos, piensa bien qué nombres de proyecto usarás, a fin de poder identificar con facilidad al emisor asociado con el proyecto.

Por ejemplo, supongamos que la API tiene clientes externos y no tienes idea de cómo se crearon los programas cliente que llaman a la API. Es posible que algunos de los clientes utilicen los servicios de Google Cloud y tengan un proyecto de Google Cloud, y quizás otros no. Para distinguir entre los emisores, debes crear un proyecto de Google Cloud separado y una clave de API para cada emisor.

Si deseas crear un proyecto de Google Cloud y una clave de API distintos para cada emisor, sigue estos pasos:

  1. Crea un proyecto por separado para cada emisor.
  2. En cada proyecto, habilita tu API y crea una clave de API.
  3. Proporciona la clave de API a cada emisor.

Crear una clave de API para cada emisor

Cuando no necesitas distinguir entre los emisores de tu API, pero quieres agregar restricciones de clave de API, puedes crear una clave de API separada para cada emisor en el mismo proyecto.

Para crear una clave de API para cada emisor en el mismo proyecto, haz lo siguiente:

  1. En el proyecto en el que está configurada la API o en un proyecto en el que la API esté habilitada, crea una clave de API para cada cliente que tenga las restricciones de clave de API que necesites.
  2. Proporciona la clave de API a cada emisor.

Crear una clave de API para todos los emisores

Cuando no necesitas distinguir entre los emisores de la API ni necesitas agregar restricciones de API, pero deseas requerir una clave de API de todos modos (por ejemplo, para impedir el acceso anónimo), puedes crear una sola clave de API que usarán todos los emisores.

Si deseas crear una clave de API para todos los emisores, haz lo siguiente:
  1. En el proyecto en el que está configurada tu API o en un proyecto en el que la API esté habilitada, crea una clave de API para todos los emisores.
  2. Proporciona la misma clave de API a todos los emisores.

¿Qué sigue?