[Yandex Cloud documentation](../../../index.md) > [Yandex API Gateway](../../index.md) > [Concepts](../index.md) > [Specification extensions](index.md) > Authorization using a Cloud Functions function

# x-yc-apigateway-authorizer:function extension

The `x-yc-apigateway-authorizer:function` extension is used within the [securityScheme](https://swagger.io/docs/specification/authentication/) component schemas of the following types:

* [HTTP Basic](https://swagger.io/docs/specification/authentication/basic-authentication/)
* [HTTP Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/)
* [API Key](https://swagger.io/docs/specification/authentication/api-keys/)

To authorize an HTTP request, API Gateway invokes the function specified in the extension. You can find out the details about the [request](#request) and [response](#response) structures below.

## Supported parameters {#parameters}

The table below lists the parameters specific to API Gateway API gateways. You can find the description of other parameters in the [OpenAPI 3.0 specification](https://github.com/OAI/OpenAPI-Specification).

Parameter | Type | Description
----|----|----
`function_id` | `string` | [Function](../../../functions/concepts/function.md) ID.
`tag` | `string` | This is an optional setting. It specifies the [tag of the function version](../../../functions/concepts/function.md#tag). The default value is `$latest`.<br>The parameters are subsituted into `tag`.
`service_account_id` | `string` | Service account ID. It is used for authorization when invoking a function. If you omit the parameter, the `service_account_id` [top-level parameter](index.md#top-level) value will be used. If the top-level parameter is also missing, the function is invoked without authorization.
`authorizer_result_ttl_in_seconds` | `int` | This is an optional setting. It sets a time limit on storing the function response in the local API Gateway cache. If this parameter is not specified, the response is not cached.
`authorizer_result_caching_mode` | `string` | This is an optional setting. It defines the authorization result caching mode. To use it, make sure to specify the `authorizer_result_ttl_in_seconds` parameter. It can be either `path` or `uri`.

## Extension specification {#spec}

Example specification for an HTTP Basic scheme:

```yaml
paths:
  /http/basic/authorize:
    get:
      summary: Authorized operation with http basic security scheme
      operationId: httpBasicAuthorize
      security:
        - httpBasicAuth: [ ]
      x-yc-apigateway-integration:
        type: dummy
        content:
          '*': "Authorized!"
        http_code: 200
        http_headers:
          'Content-Type': "text/plain"
components:
  securitySchemes:
    httpBasicAuth:
      type: http
      scheme: basic
      x-yc-apigateway-authorizer:
        type: function
        function_id: b095c95icnvb********
        tag: "$latest"
        service_account_id: ajehfe84hhl********
        authorizer_result_ttl_in_seconds: 300
```

## Request structure {#request}

Function call JSON structure:

```json
{
    "resource": <resource matching specification request>,
    "path": <actual request path>,
    "httpMethod": <HTTP method name>,
    "headers": <dictionary with HTTP header string values>,
    "queryStringParameters": <dictionary of queryString parameters>,
    "pathParameters": <dictionary of request path parameter values>,
    "requestContext": <dictionary with request context>,
    "cookies": <dictionary with request cookies>
}
```

## Response structure {#response}

Response JSON structure:

```json
{
    "isAuthorized": <authorization result, true or false>,
    "context": <dictionary with authorization context>
}
```

## Function example {#function}

Here is an example of a function that uses a response structure with an [authorization context](#context):

{% list tabs %}

- JavaScript

  ```js
  exports.handler = async function (event, context) {
      let response = {
          "isAuthorized": false
      };

      if (event.headers.Authorization === "secretToken") {
          response = {
              "isAuthorized": true,
              "context": {
                  "stringKey": "value",
                  "numberKey": 1,
                  "booleanKey": true,
                  "arrayKey": ["value1", "value2"],
                  "mapKey": {"value1": "value2"}
              }
          };
      }

      return response;
  };
  ```

{% endlist %}

`secretToken` is the authorization data of the registered user or trusted client, such as `Basic <base64(username:password)>` or `Bearer <JWT_token>`.

## Caching {#caching}

A function response is stored in the API Gateway local cache if the extension specifies the `authorizer_result_ttl_in_seconds` parameter.

The contents of a caching key depend on the authorization type and the `authorizer_result_caching_mode` value.

Authorization type | `path` caching mode | `uri` caching mode | No caching mode specified
----------------|--------------------------|-------------------------|----------------------------
[HTTP Basic](https://swagger.io/docs/specification/authentication/basic-authentication/)| `path`, `operation` (HTTP method), and `Authorization` header | `uri`, `operation` (HTTP method), and `Authorization` header | `path`, `operation` (HTTP method), and `Authorization` header
[HTTP Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/)| `path`, `operation` (HTTP method), and `Authorization` header | `uri`, `operation` (HTTP method), and `Authorization` header | `path`, `operation` (HTTP method), and `Authorization` header
[API Key](https://swagger.io/docs/specification/authentication/api-keys/)| `path`, `operation` (HTTP method), and API key | `uri`, `operation` (HTTP method), and API key                  | `path`, `operation` (HTTP method), and API key

For example, for the following specification, when sending a `/user/123` request, a caching key will be generated from `/user/{id}`, `GET`, and the `Authorization` header value. If you change the `authorizer_result_caching_mode` parameter value to `uri`, a caching key will be generated from `/user/123`, `GET`, and the `Authorization` header value.

```yaml
paths:
  /user/{id}:
    get:
      summary: Authorized operation with http basic security scheme
      operationId: httpBasicAuthorize
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: Numeric ID of the user to get
      security:
        - httpBasicAuth: [ ]
      x-yc-apigateway-integration:
        type: dummy
        content:
          '*': "Authorized!"
        http_code: 200
        http_headers:
          'Content-Type': "text/plain"
components:
  securitySchemes:
    httpBasicAuth:
      type: http
      scheme: basic
      x-yc-apigateway-authorizer:
        type: function
        function_id: b095c95icnvb********
        tag: "$latest"
        service_account_id: ajehfe84hhl********
        authorizer_result_ttl_in_seconds: 300
        authorizer_result_caching_mode: path
```

If, during the time specified in `authorizer_result_ttl_in_seconds`, another HTTP request with similar caching key components is received, API Gateway will use the cached response without invoking the function.

## Authorization context {#context}

If authorization is successful, the authorization context will be provided in the [request](../../../functions/concepts/function-invoke.md#request):

* When calling another custom [function](../../../functions/concepts/function.md): In the `requestContext.authorizer` field.
* When calling a [container](../../../serverless-containers/concepts/container.md) or HTTP request: In the `X-Yc-Apigateway-Authorization-Context` header. Data is encoded in Base64.

The authorization context may contain data identifying the user who sent the HTTP request.

## Possible errors {#errors}

* `401 Unauthorized`: Client failed to send the authorization data defined by the schema in the HTTP request (e.g., the `Authorization` header for a schema of the [HTTP Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) type).
* `403 Forbidden`: API Gateway failed to invoke the function (`"isAuthorized": false`).
* `500 Internal Server Error`: API Gateway could not invoke the function or received a function response with an incorrect structure.