# Authorizer

The authorizer section configures the authorization mechanism. ServerlessAPIGateway currently supports JWT (JSON Web Token) based authorization with HS256 algorithm.

> Serverless API Gateway now support Auth0. Check its integration [page](/configuration/auth0.md).

* `type`: Type of authorization (e.g., JWT).
* `secret`: Secret key for authorization.
* `algorithm`: Algorithm used for token validation.
* `audience`: Intended audience of the token.
* `issuer`: The issuer of the token.

**Example**

```
{
    "authorizer": {
        "type": "jwt",
        "secret": "{YOUR_SECRET_KEY}",
        "algorithm": "HS256",
        "audience": "opensourcecommunity",
        "issuer": "serverlessapigw"
    },
}
```

### JWT Error

Serverless API Gateway uses [JOSE JWT](https://github.com/panva/jose) and error states implemented with its error types. Example response:

```json
{
    "error": "Signature verification failed",
    "code": "ERR_JWS_SIGNATURE_VERIFICATION_FAILED"
}
```

### Error Codes and Responses

#### JOSEAlgNotAllowed

An error returns when a JOSE Algorithm is not allowed per developer preference.

Response

```json
{
    "error": "Algorithm not allowed",
    "code": "ERR_JOSE_ALG_NOT_ALLOWED"
}
```

#### JWEDecryptionFailed

An error returns when a JWE ciphertext decryption fails.

**Response**

```json
{
    "error": "Decryption failed",
    "code": "ERR_JWE_DECRYPTION_FAILED"
}
```

#### JWEInvalid

An error returns when the JWE format is invalid.

**Response**

```json
{
    "error": "Invalid JWE",
    "code": "ERR_JWE_INVALID"
}
```

#### JWTExpired

An error returns when a JWT has expired.

**Response**

```json
{
    "error": "Token has expired.",
    "code": "ERR_JWT_EXPIRED"
}
```

#### JWTClaimValidationFailed

An error returns when validation of a JWT claim fails.

**Response**

```json
{
    "error": "JWT claim validation failed",
    "code": "ERR_JWT_CLAIM_VALIDATION_FAILED"
}
```

#### JWTInvalid

An error returns when the JWT is invalid.

**Response**

```json
{
    "error": "Invalid JWT",
    "code": "ERR_JWT_INVALID"
}
```

#### JWKSNoMatchingKey

An error returns when no matching key is found in the JWKS.

**Response**

```json
{
    "error": "No matching key found in JWKS.",
    "code": "ERR_JWKS_NO_MATCHING_KEY"
}
```

#### JWKSInvalid

An error returns when the JWKS is invalid.

**Response**

```json
{
    "error": "Invalid JWKS",
    "code": "ERR_JWKS_INVALID"
}
```

#### JWKSMultipleMatchingKeys

An error returns when multiple matching keys are found in the JWKS.

**Response**

```json
{
    "error": "Multiple matching keys found in JWKS.",
    "code": "ERR_JWKS_MULTIPLE_MATCHING_KEYS"
}
```

#### JWSInvalid

An error thrown when the JWS is invalid.

**Response**

```json
{
    "error": "Invalid JWS",
    "code": "ERR_JWS_INVALID"
}
```

#### JWSSignatureVerificationFailed

An error returns when JWS signature verification fails.

**Response**

```json
{
    "error": "Signature verification failed",
    "code": "ERR_JWS_SIGNATURE_VERIFICATION_FAILED"
}
```

#### JWT Verification Failed

An error thrown for any other JWT verification failures not specifically covered by the other errors.

**Response**

```json
{
    "error": "JWT verification failed",
    "code": "AUTH_ERROR"
}
```

### See Also

* [Configuration Guide](/configuration/overview.md) -- full configuration reference including authorizer, CORS, and server settings.
* [Paths](/configuration/paths.md) -- define which API endpoints require authentication using the `auth` flag.
* [CORS](/configuration/cors.md) -- configure cross-origin settings that work alongside your authorization layer.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.serverlessapigateway.com/configuration/authorizer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.