Permissions and access decorators

These declarations are consumed while the CDK builder creates each Lambda function. They affect IAM policies or API Gateway authorization; they do not perform runtime authorization themselves.

grant_dynamodb

Signature: grant_dynamodb(*args, resource_key=_MISSING, access=_MISSING, table_name=_MISSING)

Example:

from lambda_api_decorators import GET, grant_dynamodb

@GET("/orders")
@grant_dynamodb("orders", "read")
def list_orders(event, context):
    return {"statusCode": 200, "body": "[]"}

Declare access to a DynamoDB table. Exactly one resource identifier is required:

Form	Meaning
grant_dynamodb("orders", "read")	Registered logical key
grant_dynamodb(resource_key="orders", access="write")	Registered logical key
grant_dynamodb(table_name="orders-prod", access="read")	Physical table name, imported by the builder

access must be "read" or "write"; read calls grant_read_data and write calls grant_read_write_data. Identifiers must be non-empty strings. More than two positional arguments, duplicate positional/keyword arguments, or both identifiers raise TypeError/ValueError during decoration. A missing or invalid access raises TypeError or ValueError.

grant_s3

Signature: grant_s3(*args, resource_key=_MISSING, access=_MISSING, bucket_name=_MISSING)

Example using a physical bucket name:

from lambda_api_decorators import GET, grant_s3

@GET("/uploads")
@grant_s3(bucket_name="uploads-prod", access="write")
def upload(event, context):
    return {"statusCode": 204, "body": ""}

This has the same forms and validation as grant_dynamodb, using an S3 bucket key or physical bucket_name. read calls grant_read and write calls grant_read_write.

permission

Signature: permission(*, actions, resources)

Declare an ALLOW IAM policy statement. Both values must be non-empty sequences of non-empty strings; strings and bytes are not accepted as sequences.

from lambda_api_decorators import GET, permission

@GET("/orders")
@permission(actions=["dynamodb:Query"], resources=["arn:aws:dynamodb:*:*:table/orders"])
def orders(event, context):
    ...

The builder applies the statement to the function role. Invalid sequence shape, empty values, or non-string members raise TypeError or ValueError.

authorizer

Signature: authorizer(key, /)

Example:

from lambda_api_decorators import GET, authorizer

@GET("/me")
@authorizer("users")
def me(event, context):
    return {"statusCode": 200, "body": "ok"}

Select the registered authorizer key for a route. key must be a non-empty string. A handler may have only one authentication declaration; combining authorizer with public raises ValueError. The CDK builder requires a compatible REST or HTTP authorizer for the selected API family.

public

Signature: public(function)

Example:

from lambda_api_decorators import GET, public

@public
@GET("/health")
def health(event, context):
    return {"statusCode": 200, "body": "ok"}

Mark a handler route as explicitly public. It is used as @public (without parentheses), and returns the same function. It cannot be combined with authorizer; public overrides the configured default authorizer for that route. It does not authenticate or change the handler at runtime.

For the CDK-side registry and default behavior, see LambdaApiConfig.